# BridgeDb MCP server

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
the [BridgeDb](https://www.bridgedb.org) identifier-mapping webservice as a small
set of curated tools, so an LLM client (Claude Desktop, Claude Code, or any
MCP-compatible client) can perform biological identifier mapping directly.

It is a thin, stateless proxy over `https://webservice.bridgedb.org` — it does
not reimplement any mapping logic. The value it adds over the raw REST API is
LLM-friendly tool descriptions, name→system-code guidance, and clean JSON output
instead of tab-delimited text.

## Tools

| Tool | Purpose |
|------|---------|
| `list_system_codes` | Translate data-source names to system codes (En, L, S, Ch, …) |
| `list_organisms` | Organisms loaded in the deployment |
| `list_source_datasources` / `list_target_datasources` | Valid source/target data sources for an organism |
| `is_mapping_supported` | Check a source→target mapping is available before requesting it |
| `xref_exists` | Check an identifier exists |
| `map_identifier` | Map one identifier to equivalents (optionally to one target) |
| `map_identifiers_batch` | Map many identifiers (same source) in one call |
| `search_identifiers` | Free-text identifier search |
| `get_attributes` | Annotation attributes (Symbol, Description, …) for an xref |

Resource `bridgedb://system-codes` returns the full system-code table.

### The one rule that matters

BridgeDb works in **xref pairs**: an identifier plus the **system code** of the
data source that issued it. Always pass the *code* (`En`), never the *name*
(`Ensembl`). Use `list_system_codes` to translate.

## Install & run

```bash
cd bridgedb-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

# stdio transport (for Claude Desktop / Claude Code)
bridgedb-mcp

# or serve over HTTP
BRIDGEDB_MCP_TRANSPORT=streamable-http bridgedb-mcp
```

## Configuration

| Env var | Default | Meaning |
|---------|---------|---------|
| `BRIDGEDB_BASE_URL` | `https://webservice.bridgedb.org` | Webservice base URL (point at a local docker container if desired) |
| `BRIDGEDB_MCP_TRANSPORT` | `stdio` | `stdio`, `sse`, or `streamable-http` |
| `BRIDGEDB_TIMEOUT` | `30` | HTTP timeout in seconds |

## Claude Desktop / Claude Code config

```json
{
  "mcpServers": {
    "bridgedb": {
      "command": "bridgedb-mcp"
    }
  }
}
```

Point `BRIDGEDB_BASE_URL` at your own deployment (e.g. the VHP4Safety
`bridgedb.cloud.vhp4safety.nl` service or a local docker container) via an `env`
block if you don't want to use the public endpoint.

## Example

> "Map the human Ensembl gene ENSG00000139618 to its HGNC symbol and UniProt ID."

The client calls `map_identifier(identifier="ENSG00000139618", source="En",
target="H")` and `map_identifier(..., target="S")`, returning `BRCA2` and
`P51587`.

## Relation to the webservice

This server is a companion to the BridgeDb webservice, whose OpenAPI spec
(`/swagger.yaml`) and `/llms.txt` guide describe the same endpoints. Those docs
are the machine-readable contract; this MCP server is the runtime tool interface
built on top of them.