使用说明
IGVF Catalog MCP Server
An MCP (Model Context Protocol) server providing LLM-friendly access to the IGVF Catalog genomics knowledge graph.
Features
- Smart Entity Lookup: Auto-detects entity type from ID patterns (genes, variants, proteins, etc.)
- Genomic Region Search: Flexible region format parsing with multi-entity queries
- Relationship Discovery: Find eQTLs, GWAS associations, protein interactions, and more
- ID Translation: Convert between variant ID formats (rsID, SPDI, HGVS, etc.)
- Data Source Discovery: Dynamically discover available datasets and filters
Installation
The server is published on PyPI as igvf-catalog-mcp. Run it without installing anything using uv:
uvx igvf-catalog-mcp
or install it with pip and run the igvf-catalog-mcp command:
pip install igvf-catalog-mcp
igvf-catalog-mcp
To use it from an MCP client such as Claude Desktop or Claude Code, register it as a stdio server:
{
"mcpServers": {
"igvf-catalog": {
"command": "uvx",
"args": ["igvf-catalog-mcp"]
}
}
}
Usage
Configure the API URL (optional):
export IGVF_CATALOG_API_URL=https://api.catalogkg.igvf.org # default
# or for development:
export IGVF_CATALOG_API_URL=https://catalog-api-dev.demo.igvf.org
export IGVF_CATALOG_API_URL=http://localhost:2023
/api is appended to the URL if it is not already there.
Tools
1. igvf_catalog_get_entity
Look up any entity by ID with automatic type detection.
{"id": "BRCA1"}
{"id": "rs12345"}
{"id": "ENSG00000141510"}
{"id": "lupus", "hint": "disease", "limit": 50, "page": 1}
2. igvf_catalog_search_region
Find all entities within a genomic region.
{"region": "chr17:41000000-42000000"}
3. igvf_catalog_find_associations
Discover relationships between entities.
{"entity_id": "TP53", "relationship": "regulatory"}
{"entity_id": "lupus", "relationship": "genetic", "hint": "disease"}
4. igvf_catalog_find_ld
Find variants in linkage disequilibrium with a query variant.
{"variant_id": "rs429358", "ancestry": "EUR", "r2_threshold": 0.8}
5. igvf_catalog_resolve_id
Convert between identifier formats.
{"id": "rs80357906"}
6. igvf_catalog_list_sources
Discover available data sources.
{"category": "gene_expression"}
Skills
Skills are pre-packaged Claude Code workflows that combine multiple tools into guided analyses. Invoke them directly with /skill-name in a Claude Code session (e.g., /igvf-catalog-variant-report rs429358). The agent can independently invoke the skills when they are relevant.
To enable skills, copy the desired skill directories from skills/ into ~/.claude/skills/ (or wherever you store your Claude Code skills).
/igvf-catalog-variant-report
Interpret a genetic variant's biological significance — disease associations, eQTLs, pharmacogenomics, coding impact, and linkage disequilibrium. Produces a structured summary of what a variant does and which conditions it's linked to.
/igvf-catalog-gene-dossier
Build a comprehensive profile of a gene — disease links, regulatory elements, protein interactions, pathways, and transcript isoforms. Useful when you want a full picture of a gene's biology and clinical relevance.
/igvf-catalog-dissect-locus
Identify the causal gene(s) at a GWAS locus by integrating LD proxies, eQTL evidence, and overlapping regulatory elements. Takes a GWAS lead variant and returns a ranked list of candidate genes with supporting evidence.
/igvf-catalog-regulatory-landscape
Map how a gene is regulated — cis-regulatory elements, eQTL variants driving its expression, and tissue-specific patterns. Highlights which regulatory variants converge on disease associations.
/igvf-catalog-disease-genes
Map the genetic architecture of a disease — causal genes, shared biological pathways, protein interaction networks, and potential therapeutic targets. Useful for understanding the gene network underlying a trait or condition.
/igvf-catalog-ld-compare
Compare linkage disequilibrium structure for a variant across ancestries (EUR, AFR, EAS, SAS). Useful for assessing PRS portability, identifying ancestry-specific tag SNPs, and understanding population differences in LD.
Development
Install from a clone with the development extras and run the linter and tests:
pip install -e ".[dev]"
ruff check
pytest
The tests run offline. tests/test_contract.py checks that every API method and parameter the server uses exists in the generated client, so it fails when the catalog API drops or renames something the server relies on.
Architecture
The server consists of:
- Tools: 6 MCP tools for genomics queries
- Services: API client, edge endpoint registry, ID parser, region parser
- Resources: Entity schemas and examples
API calls go through igvf-catalog-async-client, the async Python client generated from the IGVF Catalog OpenAPI spec. services/edge_config.py maps each relationship to a generated client method.
Versioning
The MCP server's version always equals the IGVF Catalog version it targets: igvf-catalog-mcp X.Y.Z depends on igvf-catalog-async-client==X.Y.Z. When the catalog is released, the release job pins the new client version, sets the same version in src/igvf_catalog_mcp/__init__.py, and publishes to PyPI.
Fixes to the MCP server between catalog releases are published by hand as X.Y.Z.postN (for example 1.3.0.post1): set the version in src/igvf_catalog_mcp/__init__.py, then either publish a GitHub release or run the "Publish to PyPI" workflow with workflow_dispatch.
The dev branch tracks igvf-catalog@dev; its CI installs the async client from the client repo's dev branch.
License
MIT
