Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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-mcpCodex
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. searchstrips Reactome's Solr<span class="highlighting">markup and flattens the clusteredresults[] → entries[]shape into one list.get_entryandget_event_sbmlare size-guarded so multi-MB records / SBML never flood the chat — they point you todownload_export, which streams to disk.analyze_identifiersreturns atoken; reuse it withget_analysis_results/get_analysis_not_foundto page and inspect without re-running the analysis.
Example prompts
- Search + lookup — "Search Reactome for TP53, then look up 'Transcriptional Regulation by TP53' and summarise what it does."
- Enrichment — "Run Reactome enrichment on TP53, EGFR, BRCA1, MDM2, CDKN1A and list the 5 most significant pathways with their FDR."
- SBML export — "Find 'Cell Cycle Checkpoints', export its SBML to ./reactome_downloads, and tell me how many species and reactions it defines."
- 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 respxThe 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 UIreactome-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 configAcknowledgements
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