io.github.nickzren/opentargets
Open Targets MCP server for targets, diseases, drugs, variants, and evidence
Open source Open in the app JSON README (API)
About
Open Targets MCP server for targets, diseases, drugs, variants, and evidence
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- nickzren
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.0
- Stars
- 19
- Forks
- 8
- Last push
- 2026-05-15T00:11:17Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:54
- Updated
- 2026-08-29 04:00:54
- Origin id
io.github.nickzren/opentargets
README
# Open Targets MCP Server
[](https://github.com/nickzren/opentargets-mcp/actions/workflows/ci.yml)
[](https://pypi.org/project/opentargets-mcp/)
[](https://www.python.org/)
[](https://registry.modelcontextprotocol.io/v0/servers?search=nickzren/opentargets&version=latest)
[](https://platform.opentargets.org/)
[](LICENSE)
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)
```bash
uvx --from git+https://github.com/nickzren/opentargets-mcp opentargets-mcp
```
### Option 2: Claude Desktop (MCPM)
```bash
# Install mcpm package manager
pip install mcpm
# Install the server
mcpm install opentargets
```
### Option 3: Local install (dev or self-host)
```bash
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
```bash
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)
```bash
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
```mermaid
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
```bash
# 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)
```bash
# For Claude Desktop (via mcpm) and local CLI tools
opentargets-mcp --transport stdio
```
#### **SSE transport**
```bash
# For web-based MCP clients with Server-Sent Events
opentargets-mcp --transport sse --host 0.0.0.0 --port 8000
```
#### **HTTP transport**
```bash
# 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
```bash
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:
```bash
# 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](https://platform-docs.opentargets.org/): **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
```bash
# 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
```