# kegg-mcp-server-python

[![PyPI](https://img.shields.io/pypi/v/kegg-mcp-server)](https://pypi.org/project/kegg-mcp-server/)
[![Python 3.11–3.14](https://img.shields.io/badge/python-3.11--3.14-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![CI](https://github.com/Lucas-Servi/kegg-mcp-server-python/actions/workflows/ci.yml/badge.svg)](https://github.com/Lucas-Servi/kegg-mcp-server-python/actions)

An unofficial Python [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for the [KEGG](https://www.kegg.jp) 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](https://github.com/jlowin/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](https://www.kegg.jp/kegg/rest/); 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)

```bash
uvx kegg-mcp-server
```

### With pip

```bash
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`:

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

<details>
<summary>Config file locations</summary>

| 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` |

</details>

### Claude Code

```bash
claude mcp add kegg-mcp-server -- uvx kegg-mcp-server
```

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

```bash
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](https://github.com/Lucas-Servi/kegg-mcp-server-python/releases) 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, search the ~12k organisms by code or name |
| **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 (level counts by default; `detail_level="full"` for the capped tree). Takes any id form KEGG emits — `br:ko00001`, `ko00001`, or the bare `00001` from `search_brite` |
| **Cross-database** | `batch_entry_lookup`, `convert_identifiers`, `find_related_entries` | Bulk fetch (up to 50), ID mapping within one kind — genes ↔ UniProt/NCBI, chemistry ↔ 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

```bash
# 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

```bash
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](https://elytron.bio) using [Claude Code](https://claude.ai/code).

## Acknowledgments

- Based on [Augmented-Nature/KEGG-MCP-Server](https://github.com/Augmented-Nature/KEGG-MCP-Server) -- the original TypeScript implementation that served as the foundation for this Python rewrite
- [KEGG](https://www.kegg.jp) -- Kyoto Encyclopedia of Genes and Genomes (Kanehisa Laboratories)
- [Model Context Protocol](https://modelcontextprotocol.io) -- Anthropic's open protocol for LLM tool use

## License

MIT -- see [LICENSE](LICENSE).