生命科学API MCP服务器

biosciences-mcp

FastMCP wrappers for life sciences APIs, enabling LLM agents to query biological databases for drug discovery and repurposing. Part of the Open Biosciences platform.

Status

Active — Wave 2 (Platform) migration complete. 12 FastMCP servers, 875+ tests (510 unit + 363 integration + 4 e2e, including a 175-case wire-level ADR-001 contract tier), unified gateway ready for FastMCP Cloud deployment.

What This Repo Contains

• 12 FastMCP server implementations covering HGNC, UniProt, ChEMBL, Open Targets, STRING, BioGRID, Ensembl, Entrez, PubChem, IUPHAR/GtoPdb, WikiPathways, and ClinicalTrials.gov
• 13 async client libraries for programmatic access to all servers (httpx-based)
• Pydantic v2 models including response envelopes, cross-reference schemas, and domain entities
• Unified gateway server aggregating all 12 servers behind a single endpoint (src/biosciences_mcp/servers/gateway.py)
• 875+ tests organized by pytest marker (unit, integration, e2e, contract)

All servers implement the Fuzzy-to-Fact protocol (ADR-001 §3): natural language discovery followed by strict CURIE-based lookup.

Quick Start

# Install dependencies (including dev extras)
uv sync --extra dev

# Run unit tests (no network required)
uv run pytest -m unit -v

Server Tiers

Implemented Tools by Server

Fuzzy-to-Fact Protocol

All servers enforce a two-phase workflow (ADR-001 §3):

1. Phase 1 — Fuzzy Discovery: Tools accept natural language, return ranked candidates with CURIEs
2. Phase 2 — Strict Lookup: Tools accept only resolved CURIEs (e.g., HGNC:1100, UniProtKB:P38398)
3. Failure Mode: Passing raw strings to strict tools returns UNRESOLVED_ENTITY error

# Example: fuzzy search -> CURIE resolution -> strict lookup
result = await client.call_tool("search_genes", {"query": "BRCA1"})
curie = result["items"][0]["id"]  # "HGNC:1100"
gene = await client.call_tool("get_gene", {"hgnc_id": curie})

FastMCP Cloud

Deployment is managed via the Prefect Horizon web UI at horizon.prefect.io — there is no fastmcp deploy CLI command in FastMCP 2.x. See CLAUDE.md for step-by-step instructions.

Once deployed, the gateway endpoint is:

https://biosciences-mcp.fastmcp.app/mcp

Authentication

FastMCP Cloud requires a Bearer API key. Set BIOSCIENCES_API_KEY in your environment (obtain from the Prefect Horizon console). Do not commit this key.

Connecting via Claude Code (.mcp.json)

{
  "mcpServers": {
    "biosciences-mcp": {
      "type": "http",
      "url": "https://biosciences-mcp.fastmcp.app/mcp",
      "headers": {
        "Authorization": "Bearer ${BIOSCIENCES_API_KEY}"
      }
    }
  }
}

Required Environment Variables

Set these in the Horizon console when creating the deployment:

Most life sciences APIs (HGNC, UniProt, ChEMBL, Open Targets, STRING, Ensembl, PubChem, IUPHAR/GtoPdb, WikiPathways, ClinicalTrials.gov) are fully public and require no API key.

Local Development

# Run the gateway in interactive dev mode (MCP Inspector UI)
fastmcp dev src/biosciences_mcp/servers/gateway.py

# Run a specific server
uv run fastmcp run src/biosciences_mcp/servers/hgnc.py
uv run fastmcp dev src/biosciences_mcp/servers/<server>.py

Test Commands

# By tier
uv run pytest -m unit -v                              # 510 unit tests — no network
uv run pytest -m integration -v                       # 363 integration tests — live APIs
uv run pytest -m e2e -v                               # 4 e2e tests — requires live gateway
uv run pytest -m "contract and unit" -v               # ADR-001 serialisation contract — no network
uv run pytest -m "contract and integration" -v        # ADR-001 wire contract, every server — live APIs
uv run pytest -m "not integration" -v                 # Fast local dev (unit only)

# By API
uv run pytest -m "unit and hgnc" -v
uv run pytest -m "unit and clinicaltrials" -v
uv run pytest -m "integration and chembl" -v

# E2e against the deployed cloud endpoint
FASTMCP_CLOUD_ENDPOINT=https://biosciences-mcp.fastmcp.app/mcp \
  uv run pytest -m e2e -v

Package Structure

src/biosciences_mcp/
├── clients/          # Async HTTP clients (httpx-based)
│   ├── base.py       # LifeSciencesClient base class
│   ├── hgnc.py
│   ├── uniprot.py
│   └── ...           # 13 clients total
├── models/           # Pydantic v2 models
│   ├── envelopes.py  # PaginationEnvelope, ErrorEnvelope
│   ├── cross_references.py
│   └── ...           # Domain entity models
└── servers/          # FastMCP server definitions
    ├── gateway.py    # Unified gateway (mounts all 12 servers)
    ├── hgnc.py
    └── ...           # 12 servers

Agent Ownership

Maintained by the MCP Platform Engineer agent (Agent 3). See AGENTS.md for full team definitions.

Dependencies

Related Repositories

• biosciences-program — ADRs and schemas
• biosciences-deepagents — LangGraph multi-agent system
• biosciences-temporal — Temporal durable workflows
• biosciences-research — Research workflows

License

MIT