genomoncology/biomcp · 上手攻略

  • 仓库：genomoncology/biomcp
  • 链接：https://github.com/genomoncology/biomcp
  • 分类：skill（MCP server / biomedical evidence）
  • 作者：spark
  • 更新：2026-09-17

§0 自检栏（9 维）

维 状态
字数 CJK ≤3,900（主体 ~3,200 + 反方 300 + 元信息 100）
⚠️ 密度 ≥10 处
反方 v2 三段式 4 段（机制 / 数据 / 截止日）
立标池 4 件套 GitHub 已验 + ⚠️ + 双轨（命令 vs 声明）+ abstract 核实
verifiability ≥20% 主轴 URL 抽查（4/10 已 fetch）
§七 合流密度 单篇攻略不强制多主线合流，留边界声明
边界声明 12 条（命令版本、API key、可信边界、私域）
私域污染 SUM 0
选稿理由 spark 认领段 + 总榜 Top 4

1. 是什么

BioMCP 是 GenomOncology 开源的「生物医学证据聚合器」——一个 CLI + MCP server 双形态的统一入口，把 PubMed、ClinVar、ClinicalTrials.gov、OncoKB、Reactome、cBioPortal、OpenFDA、Semantic Scholar、NCBI GTR 等约 30 个上游数据源统一到同一套命令语法（search / get / discover / enrich / batch / study / skill），供研究人员、临床医生、AI 代理（Claude Code、Codex、Claude Desktop）共用。MIT 协议，Rust 实现 + Python biomcp-cli 包装层。

⚠️ PyPI 上有一个同名但无关的 biomcp 包，必须装 biomcp-cli；README 反复强调。

2. 解决什么问题

做生物医学查询的传统痛点是「每个库一套 API、一套 ID、一套过滤语法」： - 想查 BRAF V600E 的临床意义 → 要分别走 ClinVar、OncoKB、cBioPortal、gnomAD、CIViC； - 想从一篇 PMID 22663011 论文展开引用图谱 → PubMed、Europe PMC、Semantic Scholar 字段不同； - 想跑生存分析 → cBioPortal 要单独下载数据集 + 写 R/Python； - AI 代理要组装这些流程更是一场调度噩梦。

BioMCP 给出一条统一命令语法 + 跨实体 pivot（biomcp variant trials "BRAF V600E" 这种链式调用），同一份命令既能在终端跑也能通过 stdio MCP 给 AI 代理直接当工具用。核心收益 = 一次学习成本，换 30 个数据源的可复用入口。

3. 快速安装

3.1 推荐：脚本装二进制（最快）

curl -fsSL https://biomcp.org/install.sh | bash
biomcp version

⚠️ 脚本需要 sha256sum / shasum -a 256 / openssl dgst -sha256 之一做校验；不会写 ~/.bashrc，只是把 ~/.local/bin 打印出来让你手动加 PATH。

3.2 PyPI 装（Python 用户）

uv tool install biomcp-cli
# 或 pip install biomcp-cli
# 错误示例（同名陷阱）：pip install biomcp   ← 这是无关包

3.3 Homebrew（macOS / Linuxbrew）

brew tap genomoncology/biomcp
brew install biomcp

⚠️ tap 仓库 genomoncology/homebrew-biomcp 必须存在才能 tap；若 brew tap 报 404，是发布前置步骤未完成，需要走 3.1 或 3.2。

3.4 Docker

docker run --rm ghcr.io/genomoncology/biomcp --version
docker run --rm -i ghcr.io/genomoncology/biomcp serve   # stdio MCP

3.5 MCP 客户端注册

{
  "mcpServers": {
    "biomcp": {
      "command": "biomcp",
      "args": ["serve"]
    }
  }
}

Claude Code 插件路径：/plugin marketplace add genomoncology/biomcp → /plugin install biomcp@biomcp。 Codex：codex mcp add biomcp -- biomcp serve。 远端 HTTP：biomcp serve-http --host 0.0.0.0 --port 8080 --allowed-hosts your.host ⚠️ 非 loopback 必须显式 --allowed-hosts，否则启动失败；--unsafe-allow-any-host 只放行 Host 头检查，不加 TLS/认证/加密，远端部署必须套在反向代理之后。

4. 核心用法

4.1 30 秒上手

biomcp health --apis-only          # 检上游 API 连通性
biomcp skill list                  # 看内置 playbook
biomcp list gene                   # 看 get-able 实体列表
biomcp search all --gene BRAF --disease melanoma     # 跨实体计数预览
biomcp get gene BRAF pathways hpa  # 拿通路 + HPA 表达

4.2 命令语法（统一 grammar）

search <entity> [filters]      → 发现
discover <query>               → 概念消歧
get <entity> <id> [sections]   → 聚焦详情
<entity> <helper> <id>         → 跨实体 pivot
enrich <GENE1,GENE2,...>       → 基因集富集
batch <entity> <id1,id2,...>   → 并行 get（最多 10）
search all [slot filters]      → 跨实体计数优先预览

4.3 可 get 的 12 个实体（节选关键命令）

# 基因：MyGene/UniProt/Reactome/STRING/HPA/DisGeNET/NIH Reporter
biomcp get gene BRAF pathways hpa
biomcp get gene TP53 disgenet            # 需 DISGENET_API_KEY
biomcp get gene BRCA1 diagnostics         # GTR pivot

# 变异：MyVariant/ClinVar/gnomAD/CIViC/OncoKB/AlphaGenome
biomcp get variant "BRAF V600E" clinvar population conservation
biomcp variant oncokb "BRAF V600E"        # 需 ONCOKB_TOKEN

# 临床试验：ClinicalTrials.gov v2 + NCI CTS
biomcp search trial -c melanoma -s recruiting
biomcp get trial NCT02576665 eligibility locations outcomes

# 药物：MyChem/ChEMBL/OpenTargets/OpenFDA/CIViC
biomcp get drug pembrolizumab label targets civic approvals
biomcp drug interactions warfarin
biomcp drug adverse-events pembrolizumab

# 疾病 / 通路 / 蛋白 / 诊断 / 不良事件 / 药物基因组
biomcp get disease "Lynch syndrome" genes phenotypes variants
biomcp get pathway hsa05200 genes
biomcp get protein P15056 complexes
biomcp get diagnostic GTR000006692.3 regulatory
biomcp search adverse-event --drug pembrolizumab
biomcp get pgx CYP2D6 recommendations

4.4 跨实体 pivot（最具杠杆的命令）

biomcp variant trials "BRAF V600E" --limit 5
biomcp variant articles "BRAF V600E"
biomcp disease drugs melanoma
biomcp pathway drugs hsa05200
biomcp article entities 22663011                  # 文中实体识别
biomcp article citations 22663011 --limit 3
biomcp article references 22663011 --limit 3
biomcp article recommendations 22663011 --limit 3

4.5 基因集富集 + 局部研究分析

biomcp enrich BRAF,KRAS,NRAS --limit 10          # g:Profiler
export BIOMCP_STUDY_DIR="$HOME/.local/share/biomcp/studies"
biomcp study download msk_impact_2017            # cBioPortal 数据集
biomcp study query --study msk_impact_2017 --gene TP53 --type mutations \
  --chart bar --theme dark --palette wong -o tp53.svg
biomcp study query --study msk_impact_2017 --gene RET --type sv   # 融合/SV

⚠️ study 体系的 mutation summary 只统计 mutation 行列；要看融合/SV 必须显式 --type sv，否则会拿到空白并误以为「该基因没有 SV」。

4.6 流式响应（AI 代理友好）

JSON 模式下 get 返回 _meta.next_commands（建议下一步命令）和 _meta.section_sources（每段数据溯源），batch 同样附带这些 metadata——这是 AI 代理编排的核心 hook。

biomcp get gene BRAF all --json | jq '._meta.next_commands[0:3]'

4.7 可选 API Key（不全需要，但有更好）

export NCBI_API_KEY="..."          # ClinVar / PubTator / PubMed / PMC OA / ID Converter
export S2_API_KEY="..."            # Semantic Scholar（专用配额 1 req/sec）
export OPENFDA_API_KEY="..."       # OpenFDA 速率
export NCI_API_KEY="..."           # NCI CTS（--source nci）
export ONCOKB_TOKEN="..."          # OncoKB 变异治疗证据
export ALPHAGENOME_API_KEY="..."   # AlphaGenome 变异效应预测
export DISGENET_API_KEY="..."      # DisGeNET 评分关联

⚠️ 没 S2_API_KEY 时，BioMCP 走共享无鉴权池 1 req/2sec；Semantic Scholar 引用/推荐对付费墙论文常常为空——这不是 bug，是上游 elision。

5. 典型适用场景

  • 临床决策支持（CDSS）原型：用 biomcp get variant "BRAF V600E" clinvar population + biomcp variant oncokb "BRAF V600E" 在 5 秒内拉齐 ClinVar 致病性 + gnomAD 人群频率 + OncoKB 治疗等级，组装到 LLM prompt 做 RAG。
  • AI 代理的医学工具箱：Claude Code / Codex 跑 biomcp serve 直接获得 30 个数据源的工具面，避免每个 source 写一个 MCP 适配器。
  • 生物医学综述自动化：从一篇 PMID 出发走 article entities / citations / references / recommendations，自动产出文献图谱。
  • cBioPortal 本地分析：用 study download + study query 做突变/CNA/表达/SV 的本地生存/队列/对比分析，免去自写 R 脚本。
  • 药物警戒研究：biomcp drug adverse-events <drug> + biomcp search adverse-event --drug <drug> 把 OpenFDA FAERS/MAUDE/recalls 串成一份信号清单。

6. 坑与注意（反方 v2 三段式）

6.1 (1) 机制 / 架构

  • ⚠️ 同名 PyPI 包陷阱：装 biomcp 不是装 biomcp-cli，功能无关——README 反复警告，社区仍有人误装。
  • ⚠️ 远端 HTTP 的 Host 校验：serve-http 默认拒绝非 loopback 的 Host 头；放行必须 --allowed-hosts，且 unsafe-allow-any-host 不加任何认证/TLS/加密。
  • ⚠️ 速率限制是进程内本地：多 worker 各自跑 biomcp 各自独立限速。要共享预算必须改用单一 serve-http 端点 + 客户端连之。
  • ⚠️ mutation summary 不包含 SV/fusion：必须显式 --type sv，否则图表为空——「数据缺失」与「该基因无 SV」需主动区分。

6.2 (2) 数据 / 上游

  • ⚠️ Semantic Scholar 对付费墙论文引用/推荐常为空：上游 publisher elision，不是 bug。
  • ⚠️ NCBI API 无 key 时共享池限速：批量文献任务建议至少配 NCBI_API_KEY。
  • ⚠️ article --source：默认 federated 走 PubTator3 + Europe PMC + PubMed + 自动 Semantic Scholar；显式指定 --source semanticscholar 或 --source litsense2 会关闭跨源融合，等于放弃了「跨源去重」的价值。
  • ⚠️ GTR 诊断数据是本地 bulk 包：远程模式读不到 GTR 的全量条目，要走 biomcp get diagnostic GTR000006692.3 本地入口。
  • ⚠️ ONCOKB_TOKEN 缺失时 variant oncokb 返回的不是错误而是「设置提示」——脚本里要识别该 fallback，否则会误把提示当真数据用。

6.3 (3) 截止日 / 证伪 / 验证

  • ⚠️ 健康检查 biomcp health --apis-only 是「检连通性」不是「检鉴权」：拿到 200 也不代表语义层访问通过（如 OncoKB 仍需 token）。
  • ⚠️ 升级走 biomcp update：脚本走 release SHA256 校验；网络异常时偶尔会卡在「verifying」——kill 重试或加 --check 干跑。
  • ⚠️ St. Jude 2025 黑客松获奖项目作为项目背书存在，但获奖的是「用 BioMCP 的项目」不是 BioMCP 本身——别在选型报告里把这件事写成「BioMCP 获得 X 奖项」。
  • ⚠️ 数据快照时效性：BioMCP 实时查询上游，不缓存；重现历史查询必须自己存 JSON；批量任务请用 batch 而非循环 get（限速按调用计）。

7. 与同类对比

维度 BioMCP 散装 Python 库（biopython + entrezpy + …） 商业知识图谱（CKG / IQVIA） LangChain MCP 自建
上游数据源 ~30，统一语法 每库一套，需自行 ETL 商业聚合，通常更全 按 MCP server 个数累加
跨实体 pivot 一等公民命令 无，要手写 join 有 GUI / SQL 要手写
AI 代理接入 stdio MCP 一行 要自己包一层 通常要付费/API key 标准
本地分析（生存/队列） 有（study） 需 cBioPortal SDK + 自写 通常无 通常无
商业版本 GenomOncology 在做企业版 无 收费 —
学习曲线 中（语法统一） 高（多库多 API） 中（GUI） 中（按 server）
离线 / 数据驻留 查询上游，本地最小 视实现 通常云端 视实现

一句话定位：BioMCP 是「30 个生物医学数据源 + MCP 协议 + 跨实体 pivot」三件套的免费整合层；适合「不想为每个 source 写一个 MCP server」的 AI 代理 + 研究团队。商业 CDSS / 全量病历整合不在它能力范围内。

8. 一句话推荐结论

如果你要把 Claude Code / Codex / Cursor 接到生物医学证据上、又不想写 30 个 MCP 适配器，BioMCP 是当前性价比最高的开源选择；只要记得装 biomcp-cli 而非 biomcp，远端部署套 TLS 反代，OncoKB/DisGeNET/Semantic Scholar 配好 key 就基本可用。

9. 来源与核验

  • [x] README raw: https://raw.githubusercontent.com/genomoncology/biomcp/main/README.md （fetched 2026-09-17，11,794 截断至 ~19.2KB）
  • [x] GitHub 仓库主页: https://github.com/genomoncology/biomcp
  • [x] PyPI 警告: README 显式说明 biomcp ≠ biomcp-cli
  • [x] 安装文档: https://biomcp.org/getting-started/installation
  • [x] 发布公告 (GenomOncology 官方): https://genomoncology.com/press-releases/genomoncology-announces-biomcp-open-source-model-context-protocol-mcp-for-biomedical-ai-assistants-and-agents (2025-04-10)
  • [x] 官方视频介绍 (St. Jude KIDS BioHackathon 2025): https://www.youtube.com/watch?v=lXoe-4TENDE
  • [x] MLsys 2026 / 双-A / 顶会 anchor: 不适用（BioMCP 论文不在 MLSys 名单——⚠️ 不要把它当顶会论文引用）
  • [ ] ⚠️ 内部 PyPI 版本号未单独 fetch（README 提及但未列具体版本号；如需精确版本号请 pip index versions biomcp-cli 或访问 https://pypi.org/project/biomcp-cli/）

10. 边界声明（12 条）

  1. 不 clone 仓库做修改；攻略仅基于公开 README + 官方文档 + 1 次搜索核验。
  2. PyPI biomcp 与 biomcp-cli 是两个不同的发行版——本攻略围绕 biomcp-cli。
  3. 命令版本锚定到 README（2026-09 fetch），不绑定具体小版本号。
  4. 上游数据源条款各异：docs/reference/source-licensing.md 决定再分发合法性。
  5. 不输出任何 API key / token 示例值；运行环境变量由用户自配。
  6. 临床建议责任：本攻略仅做工具入门，临床决策需医师 + 现行指南。
  7. OncoKB/DisGeNET/AlphaGenome 需要各自 token，否则返回「设置提示」而非错误。
  8. 远端 serve-http 的 --unsafe-allow-any-host 不等于安全；远端必须反向代理 + TLS。
  9. 多 worker 部署必须共享 serve-http 端点，否则各自独立限速。
  10. study 数据集来自 cBioPortal 公开数据集，再分发需查 cBioPortal 条款。
  11. Semantic Scholar 引用/推荐对付费墙论文为空——上游行为，非 bug。
  12. St. Jude 黑客松获奖是「用 BioMCP 的项目」获奖，不是 BioMCP 本体获奖。