Medical Mcps

生物学 API MCP 服务

用于研究的 MCP 服务，可集成多个生物学和医学数据库。

快速开始

连接到生产服务

使用此 MCP 服务最简单的方式是连接到生产环境部署。所有 API 均可通过统一端点访问，让你能够在一处使用所有工具。

生产环境 URL： https://mcp.cloud.curiloo.com/tools/unified/mcp

在 Cursor（或其他 MCP 客户端）中配置

将以下内容添加到 .cursor/mcp.json（或相应的 MCP 客户端配置文件）中：

{
    "mcpServers": {
        "medical-apis": {
            "url": "https://mcp.cloud.curiloo.com/tools/unified/mcp"
        }
    }
}

你将获得的功能

连接后，你将可以使用涵盖 14 个生物学和医学 API 的 100 多个工具：

• 通路：Reactome、KEGG、Pathway Commons
• 基因与蛋白质：UniProt、MyGene.info、Node Normalization
• 靶点与关联：OpenTargets Platform
• 变异：MyVariant.info、GWAS Catalog
• 疾病：OMIM、MyDisease.info
• 药物：ChEMBL、MyChem.info、OpenFDA
• 文献：PubMed/PubTator3
• 临床试验：ClinicalTrials.gov、NCI Clinical Trials
• 知识图谱：Every Cure Matrix Knowledge Graph

示例：搜索基因

{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
        "name": "mygene_get_gene",
        "arguments": {
            "gene_id_or_symbol": "TP53"
        }
    }
}

单独的 API 端点

如果你更喜欢分别使用各个 API，每个 API 都有自己的端点：

• /tools/reactome/mcp - 仅 Reactome
• /tools/pubmed/mcp - 仅 PubMed
• /tools/chembl/mcp - 仅 ChEMBL
• ...（完整列表请参阅可用端点）

本地开发

若要在本地运行自己的实例，你可以选择：

• 使用 Docker Compose（推荐用于快速设置）——参阅 Docker Compose 设置
• 直接使用 Python/uv 运行——参阅下文的运行服务

集成的 API

✅ 已实现的 API

• Reactome API - 通路信息、基因/蛋白质查询、疾病关联
• KEGG API - 通路图、基因注释、疾病和药物信息
• UniProt API - 蛋白质序列、功能注释、疾病关联
• OMIM API - 遗传性疾病信息、基因-疾病关联（需要 API 密钥）
• GWAS Catalog API - 遗传关联、变异信息、研究元数据
• Pathway Commons API - 整合的通路数据、通路相互作用、基因/蛋白质网络
• Node Normalization API - CURIE 规范化、跨数据库标识符映射
• ChEMBL API - 药物-靶点相互作用、生物活性数据、作用机制、药物适应症
• ClinicalTrials.gov API - 临床试验搜索、研究元数据、试验状态
• PubMed/PubTator3 API - 生物医学文献搜索、文章检索、预印本搜索
• OpenFDA API - FDA 不良事件报告、药品标签、医疗器械事件、药物批准信息
• OpenTargets Platform API - 靶点/疾病搜索、关联、证据
• MyVariant.info API - 遗传变异注释、人群频率、临床意义
• BioThings Suite APIs - MyGene.info（基因注释）、MyDisease.info（疾病信息）、MyChem.info（药物/化学品数据）
• NCI Clinical Trials API - 癌症临床试验搜索和元数据（需要 API 密钥）

安装

选项 1：从 PyPI 安装

从 PyPI 安装软件包：

pip install medical-mcps

然后运行服务：

medical-mcps

服务将在 http://localhost:8000 上运行。

选项 2：使用 Docker 运行

拉取并运行预构建的 Docker 镜像：

# Pull latest image
docker pull pascalwhoop/medical-mcps:latest

# Run server
docker run -p 8000:8000 pascalwhoop/medical-mcps:latest

服务将在 http://localhost:8000 上运行。

如需使用特定版本：

docker pull pascalwhoop/medical-mcps:v0.1.0

选项 3：Docker Compose（推荐用于开发）

运行 MCP 后端最简单的方式：

# Start all services with auto-rebuild
make docker-watch

# Or start in background
make docker-up

# View logs
make docker-logs

# Stop services
make docker-down

服务将在以下地址运行：

• MCP 后端：http://localhost:8000

选项 4：本地 Python 安装

# Install dependencies using uv
cd /path/to/medical-mcps
uv sync

运行服务

该服务使用 Streamable HTTP 传输（根据 MCP 规范）， 以便通过 HTTP 进行远程托管。

运行 uv sync 后，即可运行服务：

使用 Makefile（推荐用于开发）

# Start server with uvicorn and livereload (auto-reload on code changes)
make server

直接使用 uv

# Run HTTP server
uv run mcp-server

# Or with custom host/port
MCP_HOST=0.0.0.0 MCP_PORT=8000 uv run mcp-server

直接使用 uvicorn

# Run with uvicorn and livereload
uv run uvicorn medical_mcps.http_server:app --reload --host 0.0.0.0 --port 8000

HTTP 服务将在 http://localhost:8000 上运行（或使用你配置的主机和端口）。

该服务使用 MCP SDK 的 Streamable HTTP 传输，并将其作为 ASGI 应用挂载在 FastAPI 上。MCP 端点位于 /mcp，支持 POST（用于发送 JSON-RPC 消息）和 GET（用于可选的 SSE 流）。

连接到生产环境

MCP 服务已部署，可通过以下地址访问：

生产环境基础 URL： https://mcp.cloud.curiloo.com

使用情况分析： 生产环境中的工具调用会通过 Cloud Logging 记录到 BigQuery。有关架构、设置和示例查询，请参阅 docs/USAGE_ANALYTICS.md。

统一端点（推荐）

使用统一端点，即可在同一处访问所有 API：

{
    "url": "https://mcp.cloud.curiloo.com/tools/unified/mcp"
}

通过单个连接，即可访问所有 API 提供的 100 多个工具。

单独的 API 端点

如果你希望分别使用各个 API，每个 API 都有自己的端点：

生产环境：

{
    "url": "https://mcp.cloud.curiloo.com/tools/reactome/mcp"
}

本地开发：

{
    "url": "http://localhost:8000/tools/reactome/mcp"
}

可用端点

所有端点均可通过生产环境和本地 URL 访问：

• /tools/unified/mcp - 统一服务（组合所有 API）
• /tools/reactome/mcp - Reactome API
• /tools/kegg/mcp - KEGG API
• /tools/uniprot/mcp - UniProt API
• /tools/omim/mcp - OMIM API（需要 API 密钥）
• /tools/gwas/mcp - GWAS Catalog API
• /tools/pathwaycommons/mcp - Pathway Commons API
• /tools/nodenorm/mcp - Node Normalization API
• /tools/chembl/mcp - ChEMBL API
• /tools/opentargets/mcp - OpenTargets Platform API
• /tools/ctg/mcp - ClinicalTrials.gov API
• /tools/pubmed/mcp - PubMed/PubTator3 API
• /tools/openfda/mcp - OpenFDA API
• /tools/myvariant/mcp - MyVariant.info API
• /tools/biothings/mcp - BioThings Suite APIs（MyGene、MyDisease、MyChem）
• /tools/nci/mcp - NCI Clinical Trials API（需要 API 密钥）
• /tools/everycure-kg/mcp - Every Cure Matrix Knowledge Graph API

示例：在 Cursor 中配置多个 API

选项 1：使用统一端点（推荐）

通过一个连接访问所有 API：

{
    "mcpServers": {
        "medical-apis": {
            "url": "https://mcp.cloud.curiloo.com/tools/unified/mcp"
        }
    }
}

选项 2：使用单独的端点

如果你希望为每个 API 建立单独的连接：

{
    "mcpServers": {
        "reactome": {
            "url": "https://mcp.cloud.curiloo.com/tools/reactome/mcp"
        },
        "chembl": {
            "url": "https://mcp.cloud.curiloo.com/tools/chembl/mcp"
        },
        "pubmed": {
            "url": "https://mcp.cloud.curiloo.com/tools/pubmed/mcp"
        }
    }
}

测试连接

你可以通过发送简单的 HTTP 请求，测试是否能够访问生产环境中的服务：

# Test unified endpoint (recommended)
curl https://mcp.cloud.curiloo.com/tools/unified/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}'

# Or test individual API endpoint
curl https://mcp.cloud.curiloo.com/tools/reactome/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}'

如果收到成功响应，说明服务正在运行且可以访问。

HTTP 缓存

所有 API 客户端都使用 hishel（符合 RFC 9111 的 HTTP 缓存），将响应透明地缓存到磁盘。这可以减少重复的 API 调用并提升性能。

缓存配置

• 缓存位置：~/.cache/medical-mcps/api_cache/
• 缓存时长：30 天（默认 TTL）
• 缓存刷新：访问缓存条目时会重置 TTL（refresh_ttl_on_access=True）
• 按 API 划分的缓存文件：每个 API 都有自己的 SQLite 缓存文件（例如 reactome.db、kegg.db）

缓存行为

• 自动：默认对所有基于 HTTP 的 API 启用缓存
• 透明：根据 URL、参数和标头自动缓存响应
• 符合 RFC 9111：遵循 HTTP 缓存语义和 Cache-Control 标头
• 缓存可见性：提供缓存响应时，日志会显示“(from cache)”

禁用缓存

若要为特定客户端禁用缓存，请在初始化时传入 enable_cache=False：

client = ReactomeClient(enable_cache=False)

清除缓存

若要清除缓存，请删除缓存目录：

rm -rf ~/.cache/medical-mcps/api_cache/

也可以删除单个 API 缓存文件：

rm ~/.cache/medical-mcps/api_cache/reactome.db

支持的 API

所有基于 HTTP 的 API 均支持缓存：

• Reactome (httpx)
• KEGG (httpx)
• UniProt (httpx)
• OMIM (httpx)
• GWAS Catalog (httpx)
• Pathway Commons (httpx)
• ClinicalTrials.gov (requests)
• PubMed (httpx)
• OpenFDA (httpx)
• MyVariant.info (httpx)
• BioThings Suite (httpx)
• NCI Clinical Trials (httpx)

注意：ChEMBL 使用库客户端（而非 HTTP），因此缓存由库层处理。

使用 Sentry 进行监控

服务器包含可选的 Sentry 集成，用于错误跟踪和性能监控。Sentry 会自动检测 MCP 工具执行、提示词请求和资源访问。

设置

1. 从 sentry.io 获取 Sentry DSN
2. 设置 SENTRY_DSN 环境变量：

export SENTRY_DSN="https://[email protected]/project-id"

配置

可通过环境变量配置 Sentry：

• SENTRY_DSN - Sentry DSN（启用 Sentry 所必需）
• SENTRY_TRACES_SAMPLE_RATE - 性能跟踪的采样率（默认值：1.0 = 100%）
• SENTRY_SEND_DEFAULT_PII - 是否在 Sentry 中包含工具输入/输出（默认值：true）
• SENTRY_ENABLE_LOGS - 是否启用向 Sentry 发送日志（默认值：true）
• SENTRY_PROFILE_SESSION_SAMPLE_RATE - 性能分析会话的采样率（默认值：1.0 = 100%）
• SENTRY_PROFILE_LIFECYCLE - 性能分析器生命周期模式（默认值：trace - 事务处于活动状态时自动运行）
• ENVIRONMENT - 环境名称（默认值：local）

性能监控：

• 跟踪：默认捕获 100% 的事务（traces_sample_rate=1.0）
• 性能分析：默认对 100% 的会话进行性能分析（profile_session_sample_rate=1.0）
• 日志：默认启用（enable_logs=True）

跟踪内容

Sentry 会自动收集：

MCP 集成：

• 工具执行：工具名称、参数、结果和执行错误
• 提示词请求：提示词名称、参数和内容
• 资源访问：资源 URI 和访问模式
• 请求上下文：请求 ID、会话 ID 和传输类型
• 执行跨度：所有处理程序调用的计时信息

Starlette 集成：

• HTTP 请求：方法、URL、标头、表单数据、JSON 负载
• 错误：导致内部服务器错误（5xx 状态码）的所有异常
• 性能：请求计时和事务数据
• 请求数据：附加到所有事件（除非 send_default_pii=True，否则不包含 PII）

HTTPX 集成：

• 发出的 HTTP 请求：API 客户端发出的所有 HTTP 请求（Reactome、KEGG、UniProt 等）
• 请求跨度：为每个发出的 HTTP 请求创建跨度
• 跟踪传播：确保跟踪正确传播到下游服务

Asyncio 集成：

• 异步操作：跟踪异步上下文和操作
• 异步错误：捕获异步函数和任务中的错误

隐私

默认情况下，Sentry 不会包含工具输入/输出或提示词内容（这些被视为 PII）。若要包含这些数据，请设置 SENTRY_SEND_DEFAULT_PII=true。

更多详情，请参阅 Sentry MCP 集成文档。

API 密钥处理

重要：MCP 服务是一个无状态代理。它不会存储 API 密钥。

需要客户端提供 API 密钥的 API

对于需要身份验证的 API（目前为 OMIM），MCP 客户端必须在每次工具调用时将 API 密钥作为参数提供：

{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
        "name": "get_entry",
        "arguments": {
            "mim_number": "104300",
            "api_key": "your-omim-api-key-here"
        }
    }
}

需要 API 密钥的 API：

• OMIM - 所有工具都需要 api_key 参数（从 https://omim.org/api 获取）
• NCI Clinical Trials - 可选的 api_key 参数（从 https://clinicaltrialsapi.cancer.gov/ 获取）
• OpenFDA - 可选的 api_key 参数，可提高速率限制（从 https://open.fda.gov/apis/ 获取）

不需要 API 密钥的 API：

• Reactome、KEGG、UniProt、GWAS Catalog、Pathway Commons、Node Normalization、ChEMBL、 ClinicalTrials.gov、PubMed、MyVariant.info、BioThings Suite（MyGene、MyDisease、MyChem）

未来 API 的模式

如果新 API 需要身份验证，请遵循以下模式：

1. 将 api_key: str 添加为所有工具的必需参数
2. 在发起 API 调用前验证 API 密钥是否存在
3. 如果缺少密钥，则返回清晰的错误消息： "Error: API key is required. Get your API key from <url>"
4. 使用提供的密钥为每个请求创建客户端实例：client = APIClient(api_key=api_key)
5. 切勿在服务设置或环境变量中存储 API 密钥

示例：

@api_mcp.tool()
async def some_tool(param: str, api_key: str) -> str:
    """Tool description.

    Args:
        param: Required parameter
        api_key: API key (REQUIRED - get from https://api-provider.com)
    """
    if not api_key:
        return "Error: API key is required. Get your API key from https://api-provider.com"

    try:
        client = APIClient(api_key=api_key)
        return await client.some_method(param)
    except Exception as e:
        return f"Error calling API: {str(e)}"

可用工具

所有工具都以 API 名称作为前缀（例如 reactome_*），以明确指出所使用的 API。

Reactome 工具

• reactome_get_pathway - 获取详细的通路信息
• reactome_query_pathways - 按关键词或基因／蛋白质名称查询通路
• reactome_get_pathway_participants - 获取通路中的所有参与者
• reactome_get_disease_pathways - 获取与疾病相关的通路

KEGG 工具

• kegg_get_pathway_info - 按通路 ID 获取通路信息
• kegg_list_pathways - 列出通路（可按物种筛选）
• kegg_find_pathways - 查找与查询关键词匹配的通路
• kegg_get_gene - 按基因 ID 获取基因信息
• kegg_find_genes - 查找与查询关键词匹配的基因
• kegg_get_disease - 按疾病 ID 获取疾病信息
• kegg_find_diseases - 查找与查询关键词匹配的疾病
• kegg_link_pathway_genes - 获取与通路关联的基因

UniProt 工具

• uniprot_get_protein - 按登录号获取蛋白质信息
• uniprot_search_proteins - 在 UniProtKB 中搜索蛋白质
• uniprot_get_protein_sequence - 获取 FASTA 格式的蛋白质序列
• uniprot_get_disease_associations - 获取蛋白质相关的疾病关联
• uniprot_map_ids - 在不同数据库之间映射标识符

OMIM 工具

• omim_get_entry - 按 MIM 编号获取条目信息
• omim_search_entries - 在 OMIM 中搜索条目
• omim_get_gene - 按基因符号获取基因信息
• omim_search_genes - 在 OMIM 中搜索基因
• omim_get_phenotype - 按 MIM 编号获取表型信息
• omim_search_phenotypes - 在 OMIM 中搜索表型

**注意：**所有 OMIM 工具都需要 api_key 参数。从 https://omim.org/api 获取 API 密钥

GWAS Catalog 工具

• gwas_get_association - 按关联 ID 获取关联信息
• gwas_search_associations - 使用各种筛选条件搜索关联
• gwas_get_variant - 按 rsId 获取 SNP 信息
• gwas_search_variants - 按 rsId 搜索 SNP／变异
• gwas_get_study - 按研究 ID 获取研究信息
• gwas_search_studies - 使用各种筛选条件搜索研究
• gwas_get_trait - 按性状 ID 获取性状信息
• gwas_search_traits - 搜索性状

Pathway Commons 工具

• pathwaycommons_search - 搜索通路、蛋白质或其他生物实体
• pathwaycommons_get_pathway_by_uri - 根据 URI 获取通路信息
• pathwaycommons_top_pathways - 获取顶层通路（可按基因或 数据源筛选）
• pathwaycommons_graph - 获取通路图/网络（邻域、路径等）
• pathwaycommons_traverse - 使用图路径表达式遍历通路数据

Node Normalization 工具

• nodenorm_get_semantic_types - 获取所有受支持的 BioLink 语义类型
• nodenorm_get_curie_prefixes - 获取所有受支持的 CURIE 前缀
• nodenorm_get_normalized_nodes - 规范化一个或多个 CURIE，以获取等效标识符
• nodenorm_get_allowed_conflations - 获取可用的合并类型

ChEMBL 工具

• chembl_get_molecule - 根据 ChEMBL ID 获取分子（药物/化合物）信息
• chembl_search_molecules - 按名称或同义词搜索分子
• chembl_get_target - 根据 ChEMBL ID 获取靶标（蛋白质）信息
• chembl_search_targets - 按名称或同义词搜索靶标
• chembl_get_activities - 获取生物活性数据（按靶标或分子筛选）
• chembl_get_mechanism - 获取分子的作用机制
• chembl_find_drugs_by_target - 查找所有以特定蛋白质为靶标的药物
• chembl_find_drugs_by_indication - 查找针对某种疾病/适应症的所有药物
• chembl_get_drug_indications - 获取特定药物的所有适应症

OpenTargets 工具

• opentargets_search - 在 OpenTargets 平台上搜索靶标、疾病和药物
• opentargets_get_associations - 检索靶标与疾病的关联
• opentargets_get_evidence - 获取将靶标与疾病关联起来的证据

此服务遵循代码库中通用的 FastMCP + med_mcp_server 模式，而非复制外部实现；其客户端使用规范的 GraphQL 查询调用官方 OpenTargets Platform v4 GraphQL API，以搜索、检索关联和证据。

ClinicalTrials.gov 工具

• ctg_search_studies - 使用各种筛选条件搜索临床试验
• ctg_get_study - 根据 NCT ID 获取单项研究
• ctg_search_by_condition - 按病症/疾病搜索试验
• ctg_search_by_intervention - 按干预/治疗方式搜索试验
• ctg_get_study_metadata - 获取数据模型元数据（可用字段）

PubMed/PubTator3 工具

• pubmed_search_articles - 按基因、疾病、化学物质、关键词或变异，搜索 PubMed/PubTator3 上的生物医学文章
• pubmed_get_article - 根据 PMID 或 DOI 获取文章详细信息（支持全文检索）
• pubmed_search_preprints - 通过 Europe PMC 搜索 bioRxiv/medRxiv 上的预印本文章

OpenFDA 工具

• openfda_search_adverse_events - 按药物、反应或严重程度搜索 FDA 不良事件报告（FAERS）
• openfda_get_adverse_event - 根据安全性报告 ID 获取不良事件报告详情
• openfda_search_drug_labels - 按药物名称、适应症或章节搜索 FDA 药品标签（SPL）
• openfda_get_drug_label - 根据 set ID 获取完整药品标签（可选按章节筛选）
• openfda_search_device_events - 按设备、制造商或问题搜索 FDA 医疗器械不良事件报告（MAUDE）

注意： OpenFDA 工具支持可选的 api_key 参数，以提高速率限制。请从 https://open.fda.gov/apis/ 获取 API 密钥。

MyVariant.info 工具

• myvariant_search_variants - 按基因、HGVS 表示法、rsID、临床意义、频率或 CADD 评分搜索遗传变异
• myvariant_get_variant - 根据变异 ID 获取全面的变异详情（HGVS、rsID 或 MyVariant ID）

BioThings 套件工具

• mygene_get_gene - 根据 ID 或符号从 MyGene.info 获取基因信息
• mydisease_get_disease - 根据 ID 或名称从 MyDisease.info 获取疾病信息
• mychem_get_drug - 根据 ID 或名称从 MyChem.info 获取药物/化学品信息

NCI 临床试验工具

• nci_search_trials - 按病症、干预措施、阶段或状态搜索 NCI 癌症研究临床试验
• nci_get_trial - 根据试验 ID 获取 NCI 试验详情

注意： NCI 工具支持可选的 api_key 参数。请从 https://clinicaltrialsapi.cancer.gov/ 获取 API 密钥。

开发

服务的结构如下：

medical_mcps/
├── __init__.py
├── http_server.py         # HTTP MCP server (Starlette)
├── med_mcp_server.py      # Unified MCP server and tool decorator
├── settings.py            # Server configuration
├── sentry_config.py       # Sentry error tracking configuration
├── api_clients/           # API client implementations
│   ├── __init__.py
│   ├── base_client.py
│   ├── reactome_client.py
│   ├── kegg_client.py
│   ├── uniprot_client.py
│   ├── omim_client.py
│   ├── gwas_client.py
│   ├── pathwaycommons_client.py
│   ├── nodenorm_client.py
│   ├── chembl_client.py
│   ├── ctg_client.py
│   ├── pubmed_client.py
│   ├── openfda_client.py
│   ├── opentargets_client.py
│   ├── myvariant_client.py
│   ├── mygene_client.py
│   ├── mydisease_client.py
│   ├── mychem_client.py
│   └── nci_client.py
└── servers/               # Individual MCP servers per API
    ├── __init__.py
    ├── reactome_server.py
    ├── kegg_server.py
    ├── uniprot_server.py
    ├── omim_server.py
    ├── gwas_server.py
    ├── pathwaycommons_server.py
    ├── nodenorm_server.py
    ├── chembl_server.py
    ├── opentargets_server.py
    ├── ctg_server.py
    ├── pubmed_server.py
    ├── openfda_server.py
    ├── myvariant_server.py
    ├── biothings_server.py
    └── nci_server.py

添加新 API：

1. 在 api_clients/ 中创建新客户端（例如 newapi_client.py）
2. 在 servers/ 中创建新服务（例如 newapi_server.py）
3. 使用 med_mcp_server 中的 @medmcps_tool 装饰器，将工具注册到单独的服务和统一服务中
4. 在 http_server.py 中注册服务（导入、挂载并添加到生命周期管理中）
5. 遵循工具命名约定：{api_name}_{tool_name}

示例：

from ..med_mcp_server import unified_mcp, tool as medmcps_tool

@medmcps_tool(name="newapi_tool_name", servers=[newapi_mcp, unified_mcp])
async def tool_function(...):
    ...

测试

连接 MCP 客户端并调用工具来测试服务。每个工具响应都会在输出中包含 API 来源。