togomcp
dbcls/togomcp
MCP server for the RDF Portal (Public version)
Instalação
npx convez-ai dbcls/togomcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
TogoMCP: MCP Server for the RDF Portal
An MCP (Model Context Protocol) server that gives AI assistants (Claude, etc.) access to biological and biomedical RDF databases via SPARQL at the RDF Portal, as well as selected REST APIs (NCBI E-utilities, UniProt, ChEMBL, PDB, Reactome, Rhea, MeSH, and more).
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.
Local Installation
Prerequisites
- Python >= 3.11
- uv package manager
1. Install uv
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
2. Clone and install
git clone https://github.com/dbcls/togomcp.git
cd togomcp
uv sync
3. Set NCBI API Key (required for NCBI tools)
Obtain your NCBI API key and export it:
export NCBI_API_KEY="your-key-here"
Configuration
Claude Desktop
Edit your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
~\AppData\Roaming\Claude\claude_desktop_config.json
{
"mcpServers": {
"togomcp": {
"command": "/path/to/uv",
"args": [
"--directory",
"/path/to/togomcp",
"run",
"togo-mcp-local"
],
"env": {
"NCBI_API_KEY": "your-key-here"
}
}
}
}
Tip: Run
which uv(macOS/Linux) orwhere uv(Windows) to find the full path touv.
Admin Mode
Replace togo-mcp-local with togo-mcp-admin to also enable tools for generating new MIE (Metadata-Interoperability-Exchange) files — useful for contributors adding new database support.
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 production and staging endpoints side by side from the same image.
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.
Simple: docker run
For a single container without compose:
docker build -t togo-mcp .
docker run -e NCBI_API_KEY="your-key-here" -p 8000:8000 togo-mcp
Tool-Call Logging (Optional)
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. Useful for benchmarking, MIE iteration, and reconstructing multi-tool sequences.
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:
echo 'TOGOMCP_QUERY_LOG=/var/log/togomcp/togomcp.jsonl' >> .env
mkdir -p logs
docker compose up -d togomcp-main
tail -f logs/togomcp.jsonl
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:
"env": {
"NCBI_API_KEY": "your-key-here",
"TOGOMCP_QUERY_LOG": "/Users/you/togomcp-logs/togomcp.jsonl"
}
Then mkdir -p ~/togomcp-logs once and fully restart Claude Desktop.
Available Databases & Tools
TogoMCP exposes tools for querying the following (via SPARQL or REST APIs):
| Category | Resources |
|---|---|
| Proteins / Proteomics | UniProt, PDB, jPOST |
| Genes / Genomics | NCBI Gene, Ensembl, HGNC, OMA, Bgee, DDBJ |
| Chemistry | ChEMBL, PubChem, ChEBI, Rhea, BRENDA |
| Pathways | Reactome |
| Disease / Clinical | ClinVar, MedGen, MONDO, NANDO |
| Literature | PubMed, PubTator |
| Microbiology | BacDive, MediaDive, AMR Portal |
| Glycomics | GlyCosmos |
| Ontologies / Vocabulary | MeSH, GO |
| Taxonomy | NCBI Taxonomy |
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?"
Directory Structure
togomcp/
├── togo_mcp/ # Main Python package
│ ├── server.py # MCP server entry point
│ ├── main.py # Core logic and tool registration
│ ├── admin.py # Admin-mode tools (MIE generation)
│ ├── api_tools.py # REST API integrations (ChEMBL, PDB, Reactome, etc.)
│ ├── ncbi_tools.py # NCBI E-utilities tools
│ ├── rdf_portal.py # RDF Portal / SPARQL tools
│ ├── togoid.py # TogoID identifier conversion tools
│ └── data/ # Bundled data files (included in wheel)
│ ├── mie/ # MIE files (YAML, one per database)
│ ├── docs/ # Developer documentation
│ └── resources/ # Static resources (endpoints.csv, prompts, etc.)
├── benchmark/ # Benchmarking scripts and results
├── scripts/ # Utility/maintenance scripts
├── workflows/ # Example workflow prompts
├── Dockerfile # Docker build configuration
├── pyproject.toml # Python project metadata and entry points
└── uv.lock # Locked dependency versions (uv)
Contributing
Contributions are welcome! To add support for a new database, see the togo_mcp/data/mie/ directory and the admin-mode tools for generating MIE files. Please open an issue or pull request on GitHub.
Reference
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. bioRxiv. https://doi.org/10.64898/2026.03.19.713030
License
This project is licensed under the MIT License.