Medical Mcps

🚀 生物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工具執行、提示請求和資源訪問。

設置

1. 從 sentry.io 獲取你的Sentry DSN
2. 設置 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需要身份驗證，請遵循以下模式：

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:
    """工具描述。

    參數:
        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，請按照以下步驟操作：

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來源。