reactome-mcp

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."

---

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

| Tool | Signature | Purpose | |---|---|---| | search | (query, species=None, types=None, rows=10, start=0, cluster=True) | Solr free-text search; returns flattened, highlight-stripped entries + per-type counts. | | get_entry | (stable_id, enhanced=False, attribute=None, max_chars=50000) | Full record for any object by stable id/dbId; size-guarded; attribute fetches one field. | | get_entries | (stable_ids) | Batch lookup for up to 20 identifiers at once. |

Pathway hierarchy & participants

| Tool | Signature | Purpose | |---|---|---| | list_top_level_pathways | (species) | Top-level pathways (browser entry points) for a species name/taxId. | | list_pathway_events | (stable_id) | All sub-pathways and reactions contained in a pathway (recursive). | | get_event_ancestors | (stable_id) | Paths from an event up to its top-level pathway(s) — breadcrumbs. | | get_event_participants | (stable_id) | Physical entities (+ their reference entities) in a reaction/pathway. | | find_pathways_for_entity | (stable_id, species=None, all_forms=False) | Which lower-level pathways contain a given molecule/complex. |

Entities, interactors, reference data

| Tool | Signature | Purpose | |---|---|---| | get_complex_subunits | (stable_id, exclude_structures=False) | Recursively list the subunits of a complex. | | get_interactors | (accession, page=-1, page_size=-1) | Curated IntAct protein–protein interactors for an accession. | | list_species | (main_only=True) | Species annotated in Reactome (name, taxId, abbreviation). | | list_diseases | () | Diseases (Disease Ontology terms) annotated in Reactome. |

Exporters

| Tool | Signature | Purpose | |---|---|---| | get_event_sbml | (stable_id, fmt="sbml", max_chars=50000) | Export a pathway/reaction to SBML or SBGN inline; head/tail truncation past max_chars. | | download_export | (stable_id, kind="event", ext="sbml", save_dir="./reactome_downloads") | Stream an export to disk (event→sbml/sbgn, diagram/reaction/fireworks→png/svg, document→pdf). |

Enrichment analysis

| Tool | Signature | Purpose | |---|---|---| | analyze_identifiers | (identifiers, projection=True, species=None, sort_by="ENTITIES_PVALUE", p_value=1.0, page_size=20, page=1, include_interactors=False) | Submit a gene/protein list; returns a token + ranked enriched pathways with pValue/FDR. | | get_analysis_results | (token, species=None, sort_by="ENTITIES_PVALUE", p_value=1.0, page=1, page_size=20, resource="TOTAL") | Page/sort/filter a prior analysis by its token (no re-submission). | | get_analysis_not_found | (token, page=0, page_size=40) | Identifiers from the submission that did not map to Reactome. |

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