An MCP (Model Context Protocol) server that gives AI assistants (Claude, etc.) access to biological and biomedical RDF databases via SPARQL — mostly at the RDF Portal, plus a few databases' own public endpoints (GlyCosmos, TogoVar, WikiPathways, IDSM, LIPID MAPS, SwissLipids, MarpolBase) — as well as selected REST APIs (NCBI E-utilities, UniProt, ChEMBL, PDB, PubChem, Reactome, Rhea, MeSH, TogoID, TogoVar, PubCaseFinder).
MCP server for life-science knowledge graphs
Estrelas
21
Ferramentas
—
Disponibilidade
—
Quick Start: Remote Server (No Installation)
You can use the hosted TogoMCP server directly — no local setup needed.
See https://togomcp.rdfportal.org/ for connection instructions.
Tip: Run which uv (macOS/Linux) or where uv (Windows) to find the full path to uv.
Note on KEGG: TogoMCP does not enable KEGG by default. The kegg_* tools
require TOGOMCP_ENABLE_KEGG=1and the local stdio server, because the KEGG API
is licensed to academic users at academic institutions. If that is not you, simply
leave it unset and everything else works normally. See
KEGG (opt-in, local stdio only).
Docker
A Dockerfile is provided for containerized deployment.
Recommended: docker compose
compose.yaml defines two services — togomcp-main (port 8000) and togomcp-test (port 8001) — so you can run a main and a test endpoint side by side from the same image (for local and development use).
cp .env.example .env # then fill in NCBI_API_KEY
docker build -t localhost/togo-mcp:latest . # build main image (tag in .env)
docker compose up -d togomcp-main # start main endpoint
Common operations:
docker compose logs -f togomcp-main # tail logs
docker compose down # stop and remove all services
docker compose down togomcp-test # stop and remove just one
docker compose up -d togomcp-test # after rebuilding, recreates with new image
Override image tags and host ports via .env — see .env.example for the full list. Use docker compose up -d --force-recreate <svc> if compose doesn't pick up a rebuilt image, and docker image prune -f to clean up dangling layers.
Behind a reverse proxy
Two env vars matter if you put TogoMCP behind nginx/Caddy/Traefik. Both fail in ways that are easy to misdiagnose:
TOGOMCP_ALLOWED_HOSTS — FastMCP validates the Host header (DNS-rebinding protection) and answers 421 for any host not on the allow-list. The default list is localhost plus the public DBCLS vhosts, so your own hostname must be added or every proxied request is rejected.
TOGOMCP_FORWARDED_ALLOW_IPS — which peer addresses may set X-Forwarded-Proto/-For. uvicorn parses those headers but trusts only 127.0.0.1 unless told otherwise, and a container reached via a published port never arrives as loopback. Left wrong, the header is silently dropped (not rejected): the app then believes it is serving plain HTTP and emits redirects that downgrade https:// to http://. The default covers the usual container-runtime ranges; set this only if your proxy sits elsewhere.
Your proxy must also send X-Forwarded-Proto — nginx does not by default (proxy_set_header X-Forwarded-Proto $scheme;), while Caddy and Traefik do. Both halves are required; neither works alone.
TogoMCP can record every MCP tool call as one JSON line per call (timestamp,
tool name, arguments, status, elapsed_ms, session/request/client IDs, transport,
client IP). SPARQL calls are enriched with endpoint URL, HTTP code, row/byte
counts, and a SHA-256 of the query. Note the client IP is the peer address as
the app sees it — behind a proxy or container that is the proxy/gateway, the same
value for every caller, unless TOGOMCP_FORWARDED_ALLOW_IPS lets uvicorn trust
X-Forwarded-For. Useful for benchmarking, MIE iteration,
and reconstructing multi-tool sequences.
The IP is recorded as a salted hash (ip_hash) by default. Set
TOGOMCP_LOG_RAW_IP=1 to also record it in the clear as ip, which is what
lets an abusive caller be identified and blocked — at the cost of making the log
personal data (and /stats/log serves it verbatim to whoever holds the dashboard
credentials). Full field-by-field reference, including the privacy model, is in
log_file_specs.md.
On/off is a single env var: TOGOMCP_QUERY_LOG. Unset/empty = disabled
(zero-overhead default). Set to a writable file path to enable.
Output uses RotatingFileHandler (50 MB × 10, ~500 MB cap).
Docker
compose.yaml bind-mounts ./logs (and ./logs-test) on the host to
/var/log/togomcp inside each container and passes through TOGOMCP_QUERY_LOG
/ TOGOMCP_QUERY_LOG_TEST from .env. Opt in:
The path in the env var is the container-side path; the bind mount makes
the same file visible at ./logs/togomcp.jsonl on your host. Leaving the var
unset keeps logging off — no compose changes needed.
Claude Desktop (local stdio)
Add TOGOMCP_QUERY_LOG to the env block alongside NCBI_API_KEY. Use an
absolute path (the spawned process's cwd is unpredictable) and ensure the
parent directory exists:
KEGG is off by default. You do not need it, and TogoMCP is fully functional
without it — this section only matters if you are eligible and want it.
A kegg tool group (kegg_find, kegg_get_entry, kegg_pathway_graph,
kegg_pathway_neighborhood, kegg_pathway_paths, kegg_pathway_cycles,
kegg_link, kegg_conv) is mounted only when both conditions hold:
you run the local stdio entry point togo-mcp-local, and
you set TOGOMCP_ENABLE_KEGG=1.
Why two gates, for two different reasons:
The transport gate is structural and not configurable. The
KEGG API is provided "for academic use by academic
users belonging to academic institutions", and offering a service built on KEGG
additionally requires an academic service-provider license (see
KEGG's terms). A public host cannot verify a
caller's affiliation, so the hosted server at togomcp.rdfportal.org — and any HTTP
deployment — never reaches rest.kegg.jp. No environment variable can change
this; TOGOMCP_ENABLE_KEGG has no effect on the HTTP path at all.
The opt-in exists because eligibility is yours to assert. Under stdioyou are
the caller, but only you know whether your institution's access covers you. Mounting
KEGG by default would put an API call you may not be entitled to make on the path of
least resistance — an AI assistant will use any tool it can see. Leaving the variable
unset is the correct configuration for a non-academic user, and nothing else is
affected.
Calls are capped at 3 requests per second (TogoMCP enforces this process-wide, and
never retries an HTTP 403/429). KEGG is not part of RDF Portal: it has no SPARQL
endpoint, so database="kegg" is invalid in run_sparql. Use kegg_conv to translate
KEGG identifiers to UniProt, NCBI Gene/Protein, ChEBI or PubChem before querying any RDF
database with them.
Example Prompts
Once connected, you can ask your AI assistant things like:
"Find all human proteins associated with Alzheimer's disease in UniProt."
"Run a SPARQL query on the ChEMBL database to find compounds targeting EGFR."
"Search PubMed for recent papers on CRISPR base editing."
"What pathways involve the TP53 gene in Reactome?"
Adding a database: five places, not two. Only the first two affect what the server validates; the rest are documentation surfaces that drift silently, and the tests are what catch them.
togo_mcp/data/mie/<db>.yaml — the MIE file (see the MIE spec in togo_mcp/data/docs/).
uv run python scripts/generate_usage_guide_catalog.py — regenerates the Usage Guide's database catalog. Guarded by tests/test_catalog_in_sync.py.
togo_mcp/data/resources/usage_guide_v7/02_budgets_and_discovery.md — a hand-written copy of the registry that no generator touches. Bump the per-endpoint count and add the key. Guarded by TestUsageGuideEndpointTable in tests/test_server.py.
togo_mcp/data/docs/togomcp-intro.html — add a card to the database grid (not generated), and the same card to togomcp-intro-ja.html. Guarded by tests/test_trial_pages.py, which requires the two pages to match.
Note that a database removal really is just step 1: nothing validates against the other four.
Adding a tool: pass annotations=READ_ONLY_TOOL to the @mcp.tool decorator. Every TogoMCP tool is read-only, and MCP's default for an unannotated tool is the unsafe one — clients such as ChatGPT treat a tool with no readOnlyHint as a write action, which means a confirmation prompt on every call. A test asserts this, so omitting it fails the build.
Please open an issue or pull request on GitHub.
References
The system paper — describes TogoMCP as a whole (based on MIE v2):
Kinjo, A. R., Yamamoto, Y., Bustamante-Larriet, S., Labra-Gayo, J.-E., & Fujisawa, T. (2026). TogoMCP: Natural Language Querying of Life-Science Knowledge Graphs via Schema-Guided LLMs and the Model Context Protocol. Database2026:baag042. https://doi.org/10.1093/database/baag042
The MIE v3 report — the ablation study behind the current MIE format. Removing any single MIE section (or any whole functional group) turned out to be statistically null, while removing the MIE entirely cost 0.9 points out of 20 — heavy redundancy, with the query-construction content alone recovering 99% of the total effect. MIE v3 reorganizes around that evidence, matching v2 answer quality at n=100 benchmark questions while using 15% fewer input tokens and running 6% faster:
Kinjo, A. R., & Yamamoto, Y. (2026). Measure before you rewrite: ablation-driven redesign of LLM-facing RDF schema documentation in TogoMCP. BioHackrXiv. https://doi.org/10.37044/osf.io/6v5ra_v1
The MIT licence covers this code only, not the data or the third-party APIs it
reaches — each carries its own terms, and you are the caller. Most RDF Portal
databases are open, but note in particular that the KEGG API (kegg_* tools,
opt-in and local stdio only) is licensed to academic users at academic institutions
and requires a separate academic service-provider licence to redistribute as a
service — which is why it is off by default and the hosted server does not expose it at
all. See KEGG (opt-in, local stdio only).
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Togomcp?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Togomcp precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Togomcp usa?
Togomcp roda localmente via stdio.
Quando Togomcp foi verificado pela última vez?
Última verificação: 2026-11-12. MCP server for life-science knowledge graphs