reactome-db-mcp

An MCP server that gives coding agents direct SQL access to a locally hosted Reactome database — schema discovery, a guarded read-only query(), and ergonomic helpers over the full GKB relational schema, all from the chat.

Built with the official Python MCP SDK (FastMCP) over stdio. It talks straight to MySQL with pure-Python PyMySQL (run via asyncio.to_thread), so there is no build toolchain to install.

reactome-db-mcp vs reactome-mcp

They are complementary — register both:

	reactome-mcp (REST)	reactome-db-mcp (this)
Backend	Reactome REST + Analysis web services	local reactome_local MySQL DB
Needs	internet; zero setup	the local DB up (MySQL + dump loaded)
Strength	curated, pre-joined objects; enrichment p-values/FDR; always current	fast, arbitrary joins + reverse navigation over the raw 242-table schema
Use it for	"what does Reactome say about X", enrichment	bespoke relational queries the REST API never exposed

Tool names are deliberately distinct (get_object vs get_entry, search_by_name vs search, …) so both can be registered without ambiguity.

---

Prerequisites — the local database

This server needs a running MySQL with the Reactome gk_current dump loaded as reactome_local, reachable by a read-only user. On this machine that is already set up:

• MySQL 9.6 (Homebrew), database reactome_local (~990 MB, 242 MyISAM tables, Reactome release 96).
• Read-only user ro_user@localhost, empty password, SELECT-only.

If mysqld isn't running (it is not registered with brew services, so it won't survive a reboot):

brew services start mysql      # reliable auto-start, or:  /opt/homebrew/opt/mysql/bin/mysqld_safe &

To rebuild the DB from scratch, see ../reactome_local_build (keeps gk_current.sql.gz).

---

Quickstart

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

cd reactome-db-mcp
uv sync                     # install runtime deps (mcp, PyMySQL)
uv run reactome-db-mcp      # boots the server on stdio (Ctrl+C to exit)

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

"Using the reactome-db tools, look up R-HSA-69278, then list its child events in order."

---

Register with your agent

Standard stdio MCP server launched with uv run reactome-db-mcp. Run from inside the cloned directory.

Claude Code

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

Codex

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

Cursor / any other MCP client — point it at the same stdio command; a ready-to-edit example lives in .mcp.json:

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

---

Tools

All tools are async and return JSON-shaped dicts, degrading to {"error": ...} rather than raising on bad input or a down database.

Schema discovery

Tool	Signature	Purpose
schema_overview	()	Primer on the class-table-inheritance model + key joins + data release. Read first. Also the schema://reactome resource.
list_tables	(filter=None, limit=500)	Tables with exact row counts + engine; filter is a name substring (e.g. _2_).
describe_table	(table)	Columns of a table: type, nullability, key, default.

Guarded raw SQL

Tool	Signature	Purpose
query	(sql, max_rows=200)	Run one read-only statement (SELECT/WITH/SHOW/DESCRIBE/EXPLAIN). Auto-LIMIT, per-query timeout, result/cell truncation.

Ergonomic helpers (sugar over the common joins)

Tool	Signature	Purpose
get_object	(id)	Assemble a full object (stable id or DB_ID) across its inheritance chain.
search_by_name	(query, classes=None, limit=25, anchored=False)	_displayName search; anchored=True is fast, wildcard is a ~1-2s scan.
get_pathway_events	(id)	Ordered child events of a pathway (via Pathway_2_hasEvent).
get_participants	(id)	Inputs / outputs / catalysts of a reaction-like event.
get_referrers	(id, attribute=None, limit=50)	Reverse lookup — which objects point at this one (curated/best-effort).

Design notes

• Read-only by construction. The connection is a SELECT-only user (writes fail at the server), PyMySQL rejects stacked statements by default, and query() additionally checks that the statement is a single read. The string check is for clear errors, not as the security boundary — the grant is.
• Stable ids vs DB_IDs. Helpers accept either R-HSA-69278 or the numeric DB_ID. The 'R-HSA-...' text lives in StableIdentifier, joined via DatabaseObject.stableIdentifier.
• Size-guarded. Every result is row-capped (max_rows, hard ceiling 5000) and long text cells are truncated; truncated flags either.
• Point-in-time data. This is a dump (release reported by schema_overview). For the always-current Reactome, use the sibling reactome-mcp.

Configuration (env vars)

Var	Default	Meaning
REACTOME_DB_HOST / REACTOME_DB_PORT	127.0.0.1 / 3306	MySQL endpoint
REACTOME_DB_USER / REACTOME_DB_PASSWORD	ro_user / `` (empty)	credentials
REACTOME_DB_NAME	reactome_local	database
REACTOME_DB_POOL_SIZE	4	max pooled connections
REACTOME_DB_MAX_ROWS	200	default row cap
REACTOME_DB_STMT_TIMEOUT_MS	15000	per-query timeout
REACTOME_DB_MAX_CELL_CHARS	2000	per-cell text cap

---

Example prompts

1. Lookup + drill-down — "Look up R-HSA-69278 with the reactome-db tools and list its child events in order."
2. Raw SQL — "Run SELECT _class, COUNT(*) FROM DatabaseObject GROUP BY _class ORDER BY 2 DESC LIMIT 10 and summarize."
3. Reverse navigation — "Which pathways and reactions reference the object named 'CYCB:CDK1'? Use get_referrers."
4. Schema spelunking — "Call schema_overview, then describe the Pathway and Pathway_2_hasEvent tables."

---

Development

uv sync --extra dev     # pytest, pytest-asyncio
uv run pytest           # safety-layer suite runs fully offline (no DB)

# opt-in live-DB integration tests (needs reactome_local up):
REACTOME_DB_MCP_INTEGRATION=1 uv run pytest

Smoke-test the live server:

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

reactome-db-mcp/
├── src/reactome_db_mcp/
│   ├── server.py   # FastMCP app, lifespan pool, all tools + resource
│   ├── db.py       # PyMySQL pool + read-only safety layer (pure, tested)
│   └── schema.py   # curated schema primer + class-inheritance map
├── server.py       # source-checkout compatibility shim
├── tests/          # offline safety-layer suite + opt-in DB integration tests
├── pyproject.toml  # uv-managed project
├── .mcp.json       # example stdio MCP config
└── PLAN.md         # design & build record (verified 2026-06-22)

---

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