BridgeDb MCP server

A Model Context Protocol server that exposes the BridgeDb 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

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

{
  "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.