reactome-mcp

An MCP server that gives coding agents first-class access to the Reactome pathway database — search, look up, traverse, export to SBML/SBGN, and run gene-set pathway-enrichment analysis, all from the chat.

Built with the official Python MCP SDK (FastMCP) over stdio. It wraps both Reactome REST services:

• ContentService — full-text search, entity/pathway lookup, hierarchy traversal, participants, complex subunits, interactors, and SBML/SBGN/diagram export.

• AnalysisService — submit a gene/protein list and get back ranked, enriched pathways with p-value/FDR.

Because it speaks plain MCP over stdio (no vendor-specific extensions), it works with any MCP-capable agent — Claude Code, Codex, Cursor, and others. Only the registration command differs.

Quickstart

Requires uv (which manages Python ≥ 3.12 for you).

git clone https://github.com/tc2fh/reactome-mcp.git
cd reactome-mcp
uv sync                     # install runtime deps
uv run reactome-mcp         # boots the server on stdio (Ctrl+C to exit)

Then register it with your agent (see below) and ask it something like:

"Run Reactome enrichment on TP53, EGFR, BRCA1, MDM2, CDKN1A and list the 5 most significant pathways with their FDR."

Related MCP server: Oh My KEGG MCP

Register with your agent

The server is a standard stdio MCP server launched with uv run reactome-mcp. Run these from inside the cloned directory.

Claude Code

claude mcp add reactome -- uv --directory "$PWD" run reactome-mcp

Codex

codex mcp add reactome -- uv --directory "$PWD" run reactome-mcp

…or add a table to ~/.codex/config.toml:

[mcp_servers.reactome]
command = "uv"
args = ["run", "--directory", "/absolute/path/to/reactome-mcp", "reactome-mcp"]

Cursor — add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "reactome": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/reactome-mcp", "reactome-mcp"]
    }
  }
}

Any other MCP client (Windsurf, Cline, Zed, Pi, …) — point it at the same stdio command. A ready-to-edit example lives in .mcp.json:

{
  "mcpServers": {
    "reactome": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/reactome-mcp", "reactome-mcp"],
      "env": {}
    }
  }
}

Tools

All tools are async, return JSON-shaped dicts (or a path string for downloads), and degrade to {"error": ...} rather than raising on HTTP/network failures.

Search & lookup

Pathway hierarchy & participants

Entities, interactors, reference data

Exporters

Enrichment analysis

Design notes

• Reactome stable ids look like R-HSA-69278; numeric dbIds and plain accessions (e.g. P04637) are also accepted. Path identifiers are validated so they can't escape the intended endpoint.

• search strips Reactome's Solr <span class="highlighting"> markup and flattens the clustered results[] → entries[] shape into one list.

• get_entry and get_event_sbml are size-guarded so multi-MB records / SBML never flood the chat — they point you to download_export, which streams to disk.

• analyze_identifiers returns a token; reuse it with get_analysis_results / get_analysis_not_found to page and inspect without re-running the analysis.

Example prompts

1. Search + lookup — "Search Reactome for TP53, then look up 'Transcriptional Regulation by TP53' and summarise what it does."

2. Enrichment — "Run Reactome enrichment on TP53, EGFR, BRCA1, MDM2, CDKN1A and list the 5 most significant pathways with their FDR."

3. SBML export — "Find 'Cell Cycle Checkpoints', export its SBML to ./reactome_downloads, and tell me how many species and reactions it defines."

4. Hierarchy — "List the top-level human pathways, then drill into 'Cell Cycle' and show its contained events."

Development

uv sync --extra dev     # install test deps (pytest, pytest-asyncio, respx)
uv run pytest           # offline suite — every request is mocked via respx

The suite (tests/) runs entirely offline against captured fixtures in samples/, so it needs no network. Smoke-test the live server in any of these ways:

uv run reactome-mcp                          # console script
uv run python -m reactome_mcp                # module entry point
uv run python server.py                      # source-checkout shim
uv run mcp dev src/reactome_mcp/server.py    # MCP Inspector dev UI

reactome-mcp/
├── src/reactome_mcp/   # installable package (server.py = all tools + helpers)
├── server.py           # source-checkout compatibility shim
├── tests/              # offline pytest suite (respx-mocked)
├── samples/            # captured API responses used as fixtures
├── pyproject.toml      # uv-managed project
└── .mcp.json           # example stdio MCP config

Acknowledgements

Powered by Reactome, a free, open-source, open-access, curated and peer-reviewed pathway database. Please cite Reactome when publishing work that uses this data — see https://reactome.org/cite.

This project is not affiliated with or endorsed by the Reactome team.

License

MIT © Tien Comlekoglu