sparkit-mcp

sparkit-mcp

MCP server for SPARKIT — call the scientific research agent from Claude Desktop, Cursor, Claude Code, or any other MCP-compatible client.

Two tools are exposed:

• research — submit a scientific question. SPARKIT searches the

literature, reads the relevant papers, and returns a cited Markdown report. Blocks until the job finishes (default 4 min) and returns the full report inline.

• get_job_status — fetch a previously-submitted job by id. Useful

when research returned before the job finished, or to revisit a past report.

Install

uv tool install sparkit-mcp

Or with pip:

pip install sparkit-mcp

Either installs a sparkit-mcp console script. (Pre-release: install straight from GitHub with `uv tool install "git+https://github.com/SPARKIT-science/sparkit-mcp.git"` until the first PyPI release lands.)

Get an API key

1. Sign up at https://app.sparkit.science/signup (Try-it costs $10 for

5 queries; subscriptions start at $50/mo).

1. Visit https://app.sparkit.science/keys and create a key.
2. Copy the key — it's shown only once.

Configure your MCP client

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add:

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

Restart Claude Desktop. You should see sparkit appear in the tools icon next to the chat input.

If sparkit-mcp isn't on Claude Desktop's PATH (common with uv tool), use the absolute path:

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

(Find the path with which sparkit-mcp after uv tool install.)

Cursor

Edit ~/.cursor/mcp.json (or .cursor/mcp.json in your project):

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

Reload Cursor (Cmd+Shift+P → "Reload Window").

Claude Code

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

Try it

Once configured, ask the LLM:

Use SPARKIT to look up the most recent literature on the role of WRNIP1 as a synthetic-lethal target in cancer.

The LLM will call research. Expect a 60-180s wait, then a Markdown report with inline citations and a numbered Sources list.

Configuration

| Env var | Default | Description | |-------------------------------|------------------------------------------------------|-------------| | SPARKIT_API_KEY | (required) | Bearer key from https://app.sparkit.science/keys. | | SPARKIT_API_BASE | https://jlsteenwyk--sparkit-api-web.modal.run | Override the API base URL. Useful for staging or self-hosted deployments. | | SPARKIT_API_TIMEOUT_SECONDS | 30 | Per-HTTP-request timeout. Doesn't affect total wait time for research; that's max_wait_seconds. |

Tool reference

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

| Arg | Type | Default | Description | |--------------------|---------------------|---------|-------------| | question | string | — | The scientific question. Required. Be specific. | | response_format | "full" or "brief" | "full" | Length of the returned Markdown report. | | include_citations| boolean | true | Keep true for sourced reports. | | max_wait_seconds | int (30-540) | 240 | How long to block waiting before returning the job_id with instructions to poll. |

Returns Markdown. On timeout, returns a status line with the job_id so the LLM can call get_job_status later.

get_job_status(job_id)

Returns the cited Markdown report if the job has completed, a status line if it's still running, or an error message otherwise.

Troubleshooting

Authentication failed — SPARKIT_API_KEY isn't set or is invalid. Check claude_desktop_config.json for typos; restart Claude Desktop after edits.

Quota exhausted — out of monthly queries / Try-it credits. Visit https://app.sparkit.science/billing.

Tool isn't appearing in Claude Desktop — check the Claude Desktop log:

• macOS: ~/Library/Logs/Claude/mcp-server-sparkit.log
• Windows: %LOCALAPPDATA%\Claude\Logs\mcp-server-sparkit.log

The most common issue is command: sparkit-mcp not being on PATH; substitute the absolute path from which sparkit-mcp.

Job times out — max_wait_seconds cap is 540s (9 min). For very deep questions, submit then poll get_job_status instead of waiting inline. SPARKIT will also auto-cancel jobs that exceed its own internal limit.

License

MIT.