Open Targets MCP Server

A Model Context Protocol (MCP) server that exposes the Open Targets Platform GraphQL API as a set of tools for use with Claude Desktop and other MCP-compatible clients.

<!- - mcp-name: io.github.nickzren/opentargets - ->

# Quick Install

# # Option 1: Run once with uvx (no install)

uvx - -from git+https://github.com/nickzren/opentargets-mcp opentargets-mcp

# # Option 2: Claude Desktop (MCPM)

#  Install mcpm package manager
pip install mcpm

#  Install the server
mcpm install opentargets

# # Option 3: Local install (dev or self-host)

git clone https://github.com/nickzren/opentargets-mcp
cd opentargets-mcp
pip install uv
uv sync

#  Run (stdio transport by default)
uv run python -m opentargets_mcp.server

# # Option 4: Docker

git clone https://github.com/nickzren/opentargets-mcp
cd opentargets-mcp

#  Build and run with Docker Compose
docker-compose up -d - -build

Note: the default transport is http for docker deployments.

See the configuration section below for details and how to set ports and other environment variables.

# # Claude Desktop Manual Import (optional)

mcpm import stdio opentargets \
  - -command "$(uv run which python)" \
  - -args "-m opentargets_mcp.server - -transport stdio"

Then restart Claude Desktop to start using the Open Targets tools.

# Features

# # Core Capabilities

• Target Analysis: Search genes/proteins by Ensembl ID or symbol. Access expression data, genetic constraints, pathways, protein interactions, safety profiles, and mouse phenotypes
• Disease Analysis: Query diseases by EFO ID. Find associated targets, phenotypes (HPO), and research projects
• Drug Discovery: Search drugs by ChEMBL ID. Access safety data, adverse events, indications, and mechanism of action
• Evidence Mining: Explore target-disease associations with scored evidence from multiple sources
• Variant Analysis: Query genetic variants, GWAS credible sets, and pharmacogenomics data
• Study Exploration: Access GWAS studies with L2G predictions and fine-mapped loci
• Smart Search: Entity resolution with synonym handling, autocomplete, and ID mapping
• Cross-Entity Workflows: Multi-hop tools that chain disease, target, and drug evidence for prioritization
• Raw GraphQL Power Tools: Run single and batch raw GraphQL operations with structured status envelopes

# Why This Server

This implementation is designed for practical Open Targets workflows:

• Curated breadth: 65 curated tools plus 3 advanced GraphQL tools (68 total), spanning target, disease, drug, evidence, variant, study, metadata, and cross-entity workflow tasks.
• Safer automation: strict ID resolution, typed parameter handling, and resilient retry behavior.
• Lower token overhead: optional fields filters on core domain tools to return only what you need.
• Flexible power mode: raw GraphQL tools are available for edge cases.

# # Data Sources

The Open Targets Platform integrates evidence from 22+ primary data sources:

• Genetics: Open Targets Genetics, ClinVar, UK Biobank, FinnGen, Gene2Phenotype, Orphanet, COSMIC
• Functional: CRISPR screens, DepMap, GeneBass
• Drugs: ChEMBL, FDA/EMA approvals, chemical probes
• Expression: GTEx, Human Protein Atlas, Expression Atlas
• Pathways: Reactome, Signor, IntAct
• Literature: Europe PMC text mining
• Safety: FAERS, pharmacogenomics data
• Models: Mouse (MGI, IMPC) phenotypes

# Architecture

graph LR
    subgraph "Clients"
        A[Claude Desktop]
        B[Python Scripts]
        C[AI Agents]
    end
    
    subgraph "MCP Server"
        D[Open Targets<br/>MCP Server]
        E[Tool Categories<br/>Target • Disease • Drug<br/>Evidence • Search • Variant • Study]
    end
    
    subgraph "Open Targets"
        F[GraphQL API]
        G[22+ Data Sources]
    end
    
    A <- ->|MCP Protocol| D
    B <- ->|Direct API| D
    C <- ->|Function Calls| D
    D <- ->|GraphQL| F
    F <- -> G
    
    E - -> D
    
    style D fill:# e1f5fe
    style F fill:# fff3e0

The MCP server acts as a bridge between client applications and the Open Targets Platform. It translates tool calls into GraphQL queries and provides structured access to biomedical data from 22+ integrated sources.

# Prerequisites

• Python 3.10+ with pip

# Usage

# # Running the Server Standalone

#  Using the convenience script (installs uv if missing, then syncs dependencies)
./run.sh

#  Or run directly with uv (stdio transport by default)
uv run python -m opentargets_mcp.server

#  Installed entrypoints
opentargets-mcp - -help

#  Specify transport explicitly
uv run python -m opentargets_mcp.server - -transport [stdio|sse|http]

# # Configuration

• Environment variables: Transport/bind use MCP_TRANSPORT, FASTMCP_SERVER_HOST, and FASTMCP_SERVER_PORT (defaults: stdio, 0.0.0.0, 8000). API endpoint uses OPEN_TARGETS_API_URL (default: https://api.platform.opentargets.org/api/v4/graphql). For local-only development, prefer FASTMCP_SERVER_HOST=127.0.0.1.
• Validated settings: environment configuration is parsed with a typed settings model at startup (src/opentargets_mcp/settings.py), so invalid values fail fast.
• Name resolution: strict; unresolved names raise a clear error (use search_entities to find canonical IDs).
• Tool selection guidance: the server sends a short policy to clients to prefer curated tools, use fields to trim output, and reserve raw GraphQL for edge cases.
• Pagination guardrails: tool wrappers enforce page_index >= 0, page_size >= 1, and a global page_size <= 500.
• Command line: opentargets-mcp - -transport [stdio|sse|http] - -host 0.0.0.0 - -port 8000 - -api <url> provides flexible transport and endpoint selection.
• Verbose logging: add - -verbose to elevate the global log level to DEBUG when troubleshooting.
• CLI helpers: - -list-tools prints all registered tools, and - -version prints the package version.
• Rate limiting: OPEN_TARGETS_RATE_LIMIT_RPS and OPEN_TARGETS_RATE_LIMIT_BURST can enable global server-side rate limiting. - -rate-limiting and OPEN_TARGETS_RATE_LIMIT_ENABLED=true are also supported.

# # Transport Modes

The server supports multiple transport protocols powered by FastMCP:

# # # stdio transport (default)

#  For Claude Desktop (via mcpm) and local CLI tools
opentargets-mcp - -transport stdio

# # # SSE transport

#  For web-based MCP clients with Server-Sent Events
opentargets-mcp - -transport sse - -host 0.0.0.0 - -port 8000

# # # HTTP transport

#  For streamable HTTP MCP clients
opentargets-mcp - -transport http - -host 0.0.0.0 - -port 8000

# # Using with MCP Clients

• Claude Desktop: Use mcpm installation (stdio) or direct server connection (sse)
• Web MCP clients: Use SSE or HTTP transports with public URL (tunnel required)
• Custom integrations: Any transport mode depending on your client implementation

# # Example Scripts

uv run python examples/target_validation_profile.py EGFR
uv run python examples/disease_to_drug.py "schizophrenia"
uv run python examples/drug_safety_profile.py "osimertinib"
uv run python examples/genetic_target_prioritization.py "inflammatory bowel disease"

# # AI Agent Example

The ReAct Agent provides an interactive terminal interface for exploring Open Targets data:

#  Copy the example .env file and add your OpenAI API key
cp .env.example .env
#  Then edit .env and set your OPENAI_API_KEY

#  Run agent
uv run python examples/react_agent.py

The agent uses a ReAct (Reasoning and Acting) pattern to break down complex biomedical queries into steps, making it easy to explore drug targets, diseases, and their relationships.

# Available Tools

The server wraps 68 operations from the Open Targets Platform: 65 curated tools plus 3 advanced GraphQL tools. Every tool returns structured JSON that mirrors the Open Targets GraphQL schema, and you can inspect the full machine-readable list with the MCP list_tools request.

Most domain tools accept either a canonical identifier (e.g., ENSG..., EFO_..., CHEMBL...) or a human-readable name/symbol. When a name is provided, the server automatically resolves it to the best matching Open Targets ID.
Many core tools accept an optional fields list (dot-paths) to filter the response payload.
search_entities also returns search.triples for compact {id, entity, name} consumption.
For edge cases, prefer curated tools + fields first; use raw GraphQL only when no curated tool fits.

# # Quick-start shortcuts

• get_target_info – Core target identity record (Ensembl IDs, synonyms, genomic coordinates)
• get_disease_info – Disease/EFO summary with therapeutic area context
• get_drug_info – ChEMBL-backed drug profile and mechanism data
• search_entities – Unified entity search with synonym handling
• get_target_associated_diseases – High-confidence target-disease links with scores
• get_disease_associated_targets – Prioritised target list for an EFO disease
• get_target_known_drugs – Approved and investigational agents for a target
• get_target_disease_evidence – Evidence details across genetics, expression, and literature
• get_drug_repurposing_candidates – Multi-hop disease -> target -> drug candidate prioritization
• graphql_batch_query – Run one GraphQL query across many variable sets

# # Full catalog by category

• Target identity & biology (20 tools) — get_target_info, get_target_class, get_target_alternative_genes, get_target_associated_diseases, get_target_known_drugs, get_target_literature_occurrences, get_target_expression, get_target_pathways_and_go_terms, get_target_homologues, get_target_subcellular_locations, get_target_genetic_constraint, get_target_mouse_phenotypes, get_target_hallmarks, get_target_depmap_essentiality, get_target_interactions, get_target_safety_information, get_target_tractability, get_target_chemical_probes, get_target_tep, get_target_prioritization.
• Disease analytics (8 tools) — get_disease_info, get_disease_associated_targets, get_disease_phenotypes, get_disease_otar_projects, get_disease_known_drugs, get_disease_ontology, get_disease_literature_occurrences, get_disease_similar_entities.
• Drug profiling (10 tools) — get_drug_info, get_drug_cross_references, get_drug_linked_diseases, get_drug_linked_targets, get_drug_adverse_events, get_drug_pharmacovigilance, get_drug_warnings, get_drug_pharmacogenomics, get_drug_literature_occurrences, get_drug_similar_entities.
• Evidence synthesis (2 tools) — get_target_disease_evidence, get_target_disease_biomarkers.
• Search & discovery (4 tools) — search_entities, search_suggestions, get_similar_targets, search_facets.
• Metadata & ontology utilities (5 tools) — get_api_metadata, get_association_datasources, get_gene_ontology_terms, get_interaction_resources, map_ids.
• Workflow tools (1 tool) — get_drug_repurposing_candidates.
• Batch lookups (3 tools) — get_targets_batch, get_diseases_batch, get_drugs_batch.
• Variant interpretation (6 tools) — get_variant_info, get_variant_credible_sets, get_variant_pharmacogenomics, get_variant_evidences, get_variant_intervals, get_variant_protein_coordinates.
• Study exploration (6 tools) — get_study_info, get_studies_by_disease, get_study_credible_sets, get_credible_set_by_id, get_credible_set_colocalisation, get_credible_sets.
• Advanced GraphQL (3 tools) — graphql_schema, graphql_query, graphql_batch_query.

Each grouping matches the data domains described in the Open Targets docs (targets, diseases, drugs, evidence, variants, and studies). For high-volume workloads, respect the platform's throttling guidance from the Open Targets API FAQ and cache downstream where possible.

# Development

#  Run lint checks (same as CI/release)
uv run ruff check src tests

#  Run tests
uv run pytest tests/ -v

#  Inspect registered tools from CLI
uv run opentargets-mcp - -list-tools