kegg-mcp-server-python

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

Requires the MCP Python SDK v2 (mcp>=2,<3, protocol revision 2026-07-28). Versions up to 0.3.1 ran on the 1.x SDK; because mcp 2.0 removed mcp.server.fastmcp, that is a breaking dependency change, which is why this is 0.4.0 rather than a patch. Nothing changes for clients — an mcp 2.x server answers every earlier protocol revision from the same app, so a host still on the 1.x SDK connects unchanged and negotiates 2025-11-25.

Claude Desktop

Add to your claude_desktop_config.json:

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

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:

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

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

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 (lucasservi@gmail.com) 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.