sparkit-mcp

SPARKIT 的 MCP 服务器 —— 可从 Claude Desktop、Cursor、Claude Code 或任何其他兼容 MCP 的客户端调用科学研究智能体。

提供了两个工具：

• research — 提交一个科学问题。SPARKIT 会搜索文献、阅读相关论文，并返回一份带有引用的 Markdown 报告。该工具会阻塞直到任务完成（默认 4 分钟）并直接返回完整报告。

• get_job_status — 通过 ID 获取之前提交的任务。当 research 在任务完成前返回，或者需要重新查看过往报告时非常有用。

安装

uv tool install sparkit-mcp

或者使用 pip：

pip install sparkit-mcp

以上任一方式都会安装 sparkit-mcp 控制台脚本。（预发布版本：在第一个 PyPI 版本发布之前，请直接从 GitHub 安装： uv tool install "git+https://github.com/SPARKIT-science/sparkit-mcp.git"）

获取 API 密钥

1. 在 https://app.sparkit.science/signup 注册（试用版 10 美元可进行 5 次查询；订阅费用每月 50 美元起）。

2. 访问 https://app.sparkit.science/keys 并创建一个密钥。

3. 复制该密钥 —— 它仅显示一次。

配置您的 MCP 客户端

Claude Desktop

编辑 claude_desktop_config.json：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

添加：

{
  "mcpServers": {
    "sparkit": {
      "command": "sparkit-mcp",
      "env": {
        "SPARKIT_API_KEY": "sk_sparkit_..."
      }
    }
  }
}

重启 Claude Desktop。你应该会在聊天输入框旁边的工具图标中看到 sparkit。

如果 sparkit-mcp 不在 Claude Desktop 的 PATH 中（使用 uv tool 时常见），请使用绝对路径：

"command": "/Users/you/.local/bin/sparkit-mcp"

（在运行 uv tool install 后，使用 which sparkit-mcp 查找路径。）

Cursor

编辑 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "sparkit": {
      "command": "sparkit-mcp",
      "env": {
        "SPARKIT_API_KEY": "sk_sparkit_..."
      }
    }
  }
}

重新加载 Cursor（Cmd+Shift+P → “Reload Window”）。

Claude Code

claude mcp add sparkit -e SPARKIT_API_KEY=sk_sparkit_... -- sparkit-mcp

尝试一下

配置完成后，询问 LLM：

使用 SPARKIT 查找关于 WRNIP1 作为癌症合成致死靶点的最新文献。

LLM 将调用 research。预计等待 60-180 秒，然后会收到一份带有内联引用和编号来源列表的 Markdown 报告。

配置

工具参考

research(question, response_format?, include_citations?, max_wait_seconds?)

返回 Markdown。如果超时，将返回包含 job_id 的状态行，以便 LLM 稍后调用 get_job_status。

get_job_status(job_id)

如果任务已完成，返回带引用的 Markdown 报告；如果仍在运行，返回状态行；否则返回错误消息。

故障排除

身份验证失败 — SPARKIT_API_KEY 未设置或无效。检查 claude_desktop_config.json 是否有拼写错误；编辑后重启 Claude Desktop。

配额耗尽 — 每月查询次数/试用额度用尽。访问 https://app.sparkit.science/billing。

工具未在 Claude Desktop 中显示 — 检查 Claude Desktop 日志：

• macOS: ~/Library/Logs/Claude/mcp-server-sparkit.log

• Windows: %LOCALAPPDATA%\Claude\Logs\mcp-server-sparkit.log

最常见的问题是 command: sparkit-mcp 不在 PATH 中；请替换为 which sparkit-mcp 得到的绝对路径。

任务超时 — max_wait_seconds 上限为 540 秒（9 分钟）。对于非常深入的问题，请提交后轮询 get_job_status，而不是在线等待。SPARKIT 也会自动取消超过其内部限制的任务。

许可证

MIT。