JinDaGe - medical-mcps MCP Details

article

README

🚀 生物API MCP服务器

本MCP服务器集成了多个生物和医学数据库，旨在为研究工作提供便利。它整合了丰富的数据资源，让用户可以通过统一的接口访问各类生物医学工具，极大地提高了研究效率。

🚀 快速开始

连接到生产服务器

使用此MCP服务器最简单的方法是连接到生产部署。所有API都可通过一个统一端点访问，这意味着你可以在一处使用所有工具。

生产环境URL：https://medical-mcps-production.up.railway.app/tools/unified/mcp

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

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

{
  "mcpServers": {
    "medical-apis": {
      "url": "https://medical-mcps-production.up.railway.app/tools/unified/mcp"
    }
  }
}

连接后可获得的功能

连接成功后，你将可以访问来自14个生物和医学API的100多种工具：

通路相关：Reactome、KEGG、Pathway Commons
基因与蛋白质相关：UniProt、MyGene.info、Node Normalization
变异相关：MyVariant.info、GWAS Catalog
疾病相关：OMIM、MyDisease.info
药物相关：ChEMBL、MyChem.info、OpenFDA
文献相关：PubMed/PubTator3
试验相关：ClinicalTrials.gov、NCI Clinical Trials
药物再利用手册：用于探索生物医学数据路径的结构化策略

示例：搜索基因

{
  "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不良事件报告、药物标签、设备事件和药物批准信息
MyVariant.info API - 提供遗传变异注释、人群频率和临床意义信息
BioThings Suite APIs - MyGene.info（基因注释）、MyDisease.info（疾病信息）、MyChem.info（药物/化学数据）
NCI Clinical Trials API - 提供癌症临床试验搜索和元数据（需要API密钥）
药物再利用手册 - 提供用于药物再利用发现的结构化策略（请参阅PLAYBOOKS.md）

📦 安装指南

选项1：使用Docker Compose（推荐）

这是运行MCP后端和SearXNG搜索引擎最简单的方法：

# 启动所有服务并自动重建
make docker-watch

# 或者在后台启动
make docker-up

# 查看日志
make docker-logs

# 停止服务
make docker-down

服务将在以下地址可用：

MCP后端：http://localhost:8000
SearXNG：http://localhost:8888

选项2：本地Python安装

# 使用uv安装依赖项
cd /path/to/medical-mcps
uv sync

💻 运行服务器

服务器使用可流式HTTP传输协议（遵循MCP规范）进行远程HTTP托管。

运行 uv sync 后，你可以通过以下方式运行服务器：

使用Makefile（推荐用于开发）

# 使用uvicorn启动服务器并开启热重载（代码更改时自动重新加载）
make server

直接使用uv

# 运行HTTP服务器
uv run mcp-server

# 或者使用自定义主机/端口
MCP_HOST=0.0.0.0 MCP_PORT=8000 uv run mcp-server

直接使用uvicorn

# 使用uvicorn启动服务器并开启热重载
uv run uvicorn medical_mcps.http_server:app --reload --host 0.0.0.0 --port 8000

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

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

📚 连接到生产环境

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

生产环境基础URL：https://medical-mcps-production.up.railway.app

统一端点（推荐）

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

{
  "url": "https://medical-mcps-production.up.railway.app/tools/unified/mcp"
}

通过单个连接，你可以访问所有API的100多种工具。

单个API端点

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

生产环境：

{
  "url": "https://medical-mcps-production.up.railway.app/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/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/playbooks/mcp - 药物再利用手册

示例：在Cursor中配置多个API

选项1：使用统一端点（推荐） 通过一个连接访问所有API：

{
  "mcpServers": {
    "medical-apis": {
      "url": "https://medical-mcps-production.up.railway.app/tools/unified/mcp"
    }
  }
}

选项2：使用单个端点 如果你更喜欢为每个API使用单独的连接：

{
  "mcpServers": {
    "reactome": {
      "url": "https://medical-mcps-production.up.railway.app/tools/reactome/mcp"
    },
    "chembl": {
      "url": "https://medical-mcps-production.up.railway.app/tools/chembl/mcp"
    },
    "pubmed": {
      "url": "https://medical-mcps-production.up.railway.app/tools/pubmed/mcp"
    }
  }
}

测试连接

你可以通过发送一个简单的HTTP请求来测试生产服务器是否可访问：

# 测试统一端点（推荐）
curl https://medical-mcps-production.up.railway.app/tools/unified/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}'

# 或者测试单个API端点
curl https://medical-mcps-production.up.railway.app/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工具执行、提示请求和资源访问。

设置

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

export SENTRY_DSN="https://your-dsn@sentry.io/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客户端（Reactome、KEGG、UniProt等）发出的所有HTTP请求
请求跨度：为每个出站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需要身份验证，请遵循以下模式：

将 api_key: str 作为所有工具的必需参数添加
在进行API调用之前验证API密钥是否存在
如果缺少密钥，返回明确的错误消息："Error: API key is required. Get your API key from <url>"
使用提供的密钥为每个请求创建客户端实例：client = APIClient(api_key=api_key)
不要将API密钥存储在服务器设置或环境变量中

示例：

@api_mcp.tool()
async def some_tool(param: str, api_key: str) -> str:
    """工具描述。

    参数:
        param: 必需参数
        api_key: API密钥（必需 - 从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 - 获取特定药物的所有适应症

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 - 通过欧洲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 - 通过设置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 Suite工具

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

NCI Clinical Trials工具

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服务器（Starlette）
├── med_mcp_server.py      # 统一MCP服务器和工具装饰器
├── settings.py            # 服务器配置
├── sentry_config.py       # Sentry错误跟踪配置
├── api_clients/           # API客户端实现
│   ├── __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
│   ├── myvariant_client.py
│   ├── mygene_client.py
│   ├── mydisease_client.py
│   ├── mychem_client.py
│   └── nci_client.py
└── servers/               # 每个API的单个MCP服务器
    ├── __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
    ├── ctg_server.py
    ├── pubmed_server.py
    ├── openfda_server.py
    ├── myvariant_server.py
    ├── biothings_server.py
    └── nci_server.py

要添加新的API，请按照以下步骤操作：

在 api_clients/ 中创建一个新的客户端（例如，newapi_client.py）
在 servers/ 中创建一个新的服务器（例如，newapi_server.py）
使用 med_mcp_server 中的 @medmcps_tool 装饰器将工具注册到单个服务器和统一服务器
在 http_server.py 中注册服务器（导入、挂载和生命周期）
遵循命名约定：工具名称采用 {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来源。

medical-mcps

README

🚀 生物API MCP服务器

🚀 快速开始

连接到生产服务器

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

连接后可获得的功能

示例：搜索基因

单个API端点

本地开发

✨ 集成的API

✅ 已实现的API

📦 安装指南

选项1：使用Docker Compose（推荐）

选项2：本地Python安装

💻 运行服务器

使用Makefile（推荐用于开发）

直接使用uv

直接使用uvicorn

📚 连接到生产环境

统一端点（推荐）

单个API端点

可用端点

示例：在Cursor中配置多个API

测试连接

🔧 HTTP缓存

缓存配置

缓存行为

禁用缓存

清除缓存

支持缓存的API

🔧 使用Sentry进行监控

设置

配置

监控内容

隐私

🔧 API密钥处理

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

未来API的处理模式

🔧 可用工具

Reactome工具

KEGG工具

UniProt工具

OMIM工具

GWAS Catalog工具

Pathway Commons工具

Node Normalization工具

ChEMBL工具

ClinicalTrials.gov工具

PubMed/PubTator3工具

OpenFDA工具

MyVariant.info工具

BioThings Suite工具

NCI Clinical Trials工具

🔧 开发

🔧 测试

Runtime guide

Hosted runtime

Local runtime / other methods