Kegg Mcp Server Python

PyPI Python 3.11–3.14 License: MIT CI

An unofficial Python Model Context Protocol (MCP) server for the KEGG bioinformatics database. It exposes 34 tools, 9 resource templates, and 4 guided prompts to any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.). Developed by Elytron Biotech.

Built with FastMCP, returns structured Pydantic JSON (not raw text), and includes per-operation TTL caching, request retry with exponential backoff, a three-request-per-second rate limit, structured JSON stderr logging, and batch helpers out of the box. No API key is required.

Responses are token-aware by default: get_*_info tools return a compact EntrySummary (entry id, name, class, description, counts of linked entities) unless you pass detail_level="full". Errors are returned as a typed ErrorResult the model can reason about, not raised as exceptions.

Usage notice: This is a community project and is not affiliated with or endorsed by KEGG or Kanehisa Laboratories. KEGG states that its REST API is for academic use by academic users; non-academic users must follow KEGG's linked non-academic-use guidance. Users are responsible for ensuring that their use complies with those terms.

---

Quick start

With uvx (no install)

uvx kegg-mcp-server

With pip

pip install kegg-mcp-server
kegg-mcp-server

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "kegg": {
      "command": "uvx",
      "args": ["kegg-mcp-server"]
    }
  }
}

Config file locations

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Claude Code

claude mcp add kegg-mcp-server -- uvx kegg-mcp-server

Or install as a plugin (includes slash commands, agent, and skill):

claude plugin install Lucas-Servi/kegg-mcp-server-python

The plugin bundles:

Type	Name	Description
Command	/kegg <query>	Quick search across all KEGG databases
Command	/kegg-pathway <id>	Pathway deep-dive with ASCII visualization
Command	/kegg-drug <name>	Drug targets, pathways, and interactions
Agent	kegg-bioinformatics	Auto-invoked for biological pathway/gene/drug questions
Skill	kegg-analysis	Multi-step workflow guide (enrichment, comparison, investigation)

MCPB bundle (Linux x86-64 only, no Python install required)

The release bundle is built specifically for Linux x86-64 and CPython 3.12 because it vendors native dependencies. Download the linux-x86_64-py312.mcpb artifact from the releases page and drag it onto Claude Desktop. On macOS or Windows, use the cross-platform uvx, pip, or Claude Code plugin installation above.

---

What's included

34 Tools

Category	Tools	Examples
Database	get_database_info, list_organisms	Get KEGG release stats, list all ~26k organisms
Pathways	search_pathways, get_pathway_info, get_pathway_genes, get_pathway_compounds, get_pathway_reactions	Search by keyword, get full pathway details
Genes	search_genes, get_gene_info, get_gene_orthologs	Find genes in any organism, cross-species orthologs
Compounds	search_compounds, get_compound_info, get_compound_reactions	Search by name/formula/mass, find reactions
Reactions	search_reactions, get_reaction_info	Equation, enzymes, pathways for any reaction
Enzymes	search_enzymes, get_enzyme_info	EC number lookup, substrates, genes
Diseases	search_diseases, get_disease_info	Disease genes, drugs, pathways
Drugs	search_drugs, get_drug_info, get_drug_interactions	Drug targets, DDI screening
Modules	search_modules, get_module_info	Functional module definitions
Orthology	search_ko_entries, get_ko_info	KEGG Orthology entries
Glycans	search_glycans, get_glycan_info	Glycan composition, reactions
BRITE	search_brite, get_brite_info	Functional hierarchies
Cross-database	batch_entry_lookup, convert_identifiers, find_related_entries	Bulk fetch (up to 50), ID mapping (UniProt, NCBI, ChEBI, PubChem)
Visualization	render_pathway_ascii	ASCII art rendering of pathway topology (chain or grid mode)

9 Resource Templates

Direct URI-based access to KEGG entities:

kegg://pathway/{pathway_id}        e.g. kegg://pathway/hsa00010
kegg://gene/{gene_id}              e.g. kegg://gene/hsa:1956
kegg://compound/{compound_id}      e.g. kegg://compound/C00002
kegg://reaction/{reaction_id}      e.g. kegg://reaction/R00756
kegg://disease/{disease_id}        e.g. kegg://disease/H00004
kegg://drug/{drug_id}              e.g. kegg://drug/D00001
kegg://organism/{org_code}         e.g. kegg://organism/hsa
kegg://pathway/{pathway_id}/ascii  e.g. kegg://pathway/hsa00010/ascii
kegg://search/{database}/{query}   e.g. kegg://search/compound/glucose

4 Guided Prompts

Prompt	Arguments	What it does
pathway_enrichment_analysis	gene_list, organism	Maps a gene list to KEGG IDs, aggregates pathway associations, identifies enriched pathways
drug_target_investigation	drug_name	Drug lookup, target identification, pathway mapping, DDI screening
metabolic_pathway_comparison	pathway_id, organisms	Compares gene/compound content of a pathway across species
visualize_pathway	pathway_id, organism	Renders pathway as ASCII art (chain + grid), annotates key steps

---

ASCII Pathway Renderer

The render_pathway_ascii tool converts KEGG pathway topology (from KGML XML) into LLM-friendly ASCII text. Two styles are available:

Chain mode (default) — linear reaction flow:

Glycolysis / Gluconeogenesis (hsa)
====================================

[alpha-D-Gl~] ──R01786──▶ [beta-D-Gl~] ──R01600──▶ [beta-D-F~]

Grid mode — 2D spatial layout using KGML coordinates:

Glycolysis / Gluconeogenesis (hsa)
====================================

  [Glc]────────▶[G6P]────────▶[F6P]
                  │
                  ▼
                [6PG]

Legend:
  [Glc] = alpha-D-Glucose (cpd:C00267)
  [G6P] = D-Glucose 6-phosphate (cpd:C00092)

---

Transport options

# stdio (default -- for Claude Desktop, Claude Code, uvx)
kegg-mcp-server

# Streamable HTTP (for web/API deployment)
kegg-mcp-server --transport streamable-http --host 0.0.0.0 --port 8080

# python -m also works
python -m kegg_mcp_server

---

Development

git clone https://github.com/Lucas-Servi/kegg-mcp-server-python
cd kegg-mcp-server-python
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check src/ tests/

# Debug with MCP Inspector
mcp dev kegg-mcp-server

Project structure

src/kegg_mcp_server/
  server.py       FastMCP instance, lifespan (httpx client + TTL cache), CLI
  client.py       KEGGClient: async KEGG REST with retry/backoff + KEGG-politeness semaphore
  cache.py        Per-op TTL cache (info 24h, list 1h, entry ops 5min)
  parsers.py      KEGG flat-file and tab-delimited response parsers + summarize_flat_entry
  errors.py       KEGGAPIError exception type
  logging.py      JSON stderr logger (stdout is reserved for MCP stdio framing)
  resources.py    8 MCP resource templates
  prompts.py      3 bioinformatics workflow prompts
  models/         Pydantic models for all KEGG entity types + EntrySummary + ErrorResult
  tools/          13 tool modules, each with a register(mcp) function; _common.py has the
                  @kegg_tool error-boundary decorator and shared READ_ONLY annotations

---

Author

Developed by Lucas Servi ([email protected]) at Elytron Biotech using Claude Code.

Acknowledgments

• Based on Augmented-Nature/KEGG-MCP-Server -- the original TypeScript implementation that served as the foundation for this Python rewrite
• KEGG -- Kyoto Encyclopedia of Genes and Genomes (Kanehisa Laboratories)
• Model Context Protocol -- Anthropic's open protocol for LLM tool use

License

MIT -- see LICENSE.