# 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 **35 tools**, **9 resource templates**, and **4 guided prompts** to any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.). Developed by **Elytron Biotech**.

Built on the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) v2 (`MCPServer`), 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"`. List- and mapping-shaped outputs are capped at 100 items and report the full count plus `truncated`. Failures are MCP tool errors (`isError: true`) whose text is a typed `ErrorResult` JSON (`code`, `retryable`, `hint`) the model can reason about.

> **0.5.0 changes output shapes:** failures (including not-found) are now `isError: true` instead of a normal result; `convert_identifiers` maps each source ID to a **list** of targets; link/ortholog/pathway-gene/DDI outputs are capped with `truncated`; `batch_entry_lookup` returns summaries unless `detail_level="full"`; logging is configured with `--log-level` / `--log-tracebacks` instead of environment variables.

> **0.6.0 adds `draw_pathway_map`:** a PNG pathway map with gene boxes coloured by KO/EC groups, redrawn from KGML (new dependency: Pillow). See [Pathway map images](#pathway-map-images).

> **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 marketplace add Lucas-Servi/kegg-mcp-server-python
claude plugin install kegg-mcp-server@kegg-mcp-server
```

Or, in one step (Claude Code v2.1.292+), pointing `install` at the marketplace directly:

```bash
claude plugin install kegg-mcp-server --marketplace Lucas-Servi/kegg-mcp-server-python
```

The plugin starts a local (stdio) MCP server, so it works in Claude Code, Cowork, and Claude Desktop, but not in the claude.ai web app.

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

### 35 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`, `draw_pathway_map` | ASCII art rendering of pathway topology (chain or grid mode); a PNG map with gene boxes coloured by KO/EC groups (e.g. one per genome) |

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

---

## Pathway map images

`draw_pathway_map` draws a KEGG map as a PNG and colours its gene boxes by up to 8
highlight groups, for example one per genome:

```json
{"pathway_id": "map00010",
 "highlight": {"Strain A": ["K00844", "K01810", "EC:4.1.2.13"],
               "Strain B": ["K01810", "2.7.1.11"]}}
```

- Every box is split into one stripe per group: coloured when the group has one of the box's
  KOs, grey when it doesn't. A KO without a direct match is coloured through EC numbers when
  **one item** carries every EC KEGG links to that KO (listed as `matched_by_ec`, a less specific
  match than a KO). An item may hold one gene's ids separated by spaces, e.g. a GenBank
  `db_xref` string as is, so a bifunctional KO isn't lit by two unrelated single-function genes.
- The image is **redrawn from KGML** (boxes, compounds, reaction lines, links to other maps)
  with Pillow; KEGG's own map bitmap is not fetched or redistributed. The footer credits KEGG.
- The result is a text block with the summary JSON (also `structuredContent`) and an image
  block (`image/png`). The summary lists, per group, the map KOs found and boxes coloured, and per
  box its KOs and the groups that have it, so an agent can check the figure without vision.
- `map`, `ko`, organism (`eco00020`, drawn as the KO reference map) and bare (`00010`) ids are
  accepted. Global/overview maps (011xx, 012xx) are refused with `code: "global_map"`.
- The drawing code is importable without MCP: `kegg_mcp_server.pathway_map.build_pathway_map(
  kegg_client, pathway_id, groups)` returns the PNG bytes and the same summary.

---

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

# Logging (stderr, JSON): verbosity and full tracebacks
kegg-mcp-server --log-level DEBUG --log-tracebacks
```

---

## Data handling

- The only network destination is the public KEGG REST API at `https://rest.kegg.jp` (all tools, resources, and the ASCII renderer's KGML fetch go there). Queries you make (IDs, search terms) are sent to KEGG; nothing is sent anywhere else, and there is no telemetry.
- Responses are cached in memory only (per-operation TTL) and discarded when the server exits; nothing is written to disk.
- Logs are structured JSON on stderr only, on your machine.
- No API key or account, and the server reads no environment variables of its own (logging is set by CLI flags). The HTTP client (httpx) honours the standard proxy and CA-bundle variables (`HTTPS_PROXY`, `NO_PROXY`, `SSL_CERT_FILE`, …) so it works behind corporate proxies.
- The `uvx` launcher downloads the pinned `kegg-mcp-server` package and its dependencies from PyPI on first run.

---

## 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       MCPServer 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, 64 MiB budget (info 24h, list 1h, entry ops 6h)
  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    9 MCP resource templates
  prompts.py      4 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).