BioMCP: Biomedical Model Context Protocol

BioMCP

一个二进制文件。一套语法。来自你已信赖的生物医学数据源的证据。

数据条款

BioMCP 从上游生物医学数据源检索数据。各数据源的条款决定了你如何使用其返回的数据：有些限制商业用途或临床用途。在依赖这些数据之前，请查看各数据源的条款并获取所需的许可。请参阅数据源许可与条款，了解各数据源的具体说明。

什么是 BioMCP？

BioMCP 是一个 CLI 二进制文件，采用一套统一的命令语法，可直接访问 72 个可信的生物医学数据源（PubMed、ClinVar、ClinicalTrials.gov、OncoKB、Reactome 等；另有 10 个数据源会出现在其他数据源的回答中）。它也是一个 MCP（Model Context Protocol）服务，因此 Claude Code、Codex 和 Claude Desktop 等 AI Agent 都可以使用同一套工具。

BioMCP 消除了常见的生物医学数据迷宫：只需一次查询，即可访问通常分散在不同 API、标识符和搜索习惯背后的数据源。研究人员、临床医生和 Agent 使用同一套命令语法进行搜索、聚焦和切换，无需为每个数据源重新构建工作流。你可以从实时公共数据和本地研究分析中获取精简、以证据为导向的结果。

功能

• 搜索文献： search article 会在筛选条件兼容时并行查询 PubTator3、Europe PMC 和 PubMed，去重 PMID/PMCID/DOI 标识符；筛选条件适用时，还可以添加 Semantic Scholar 查询。
• 轻松切换： 从基因、变异、药物、疾病、通路、蛋白质或文章，直接切换到下一个内置视图，无需手动重新构建筛选条件。
• 选择操作手册： biomcp skill list 会显示随附的完整示例，你可以打开匹配的 biomcp skill <slug> 工作流。
• 在本地分析研究： study 命令支持本地查询、队列、生存分析、比较和共现工作流，可为下载的 cBioPortal 风格数据集生成原生终端图表、SVG 和 PNG 图表。
• 追踪论文线索： article citations、article references、article recommendations 和 article entities 可以将一篇已知论文扩展为更广泛的证据图谱。
• 富集分析与批量处理： 使用 biomcp enrich 进行顶层 g:Profiler 富集分析，使用 biomcp batch 在一条命令中执行最多 10 次聚焦的 get 调用。

快速开始

不到 30 秒即可执行第一个有效查询：

uv tool install biomcp-cli
biomcp health --apis-only
biomcp skill list
biomcp list gene
biomcp search all --gene BRAF --disease melanoma  # unified cross-entity discovery
biomcp get gene BRAF pathways hpa

观看介绍视频

一个使用 BioMCP 的项目赢得了 St. Jude 2025 年 KIDS BioHackathon 的冠军。随后举行的演讲是对 BioMCP 的一小时介绍，录制于 2025 年 10 月 24 日。

在 YouTube 上观看 · 阅读演讲记录 · 完整文字稿

安装

安装二进制文件

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

安装 PyPI 工具

uv tool install biomcp-cli
# or: pip install biomcp-cli

PyPI 软件包警告： 请安装 biomcp-cli，而非 biomcp。PyPI 上的 biomcp 软件包与本项目无关。

MCP Registry 所有权标记：mcp-name: io.github.genomoncology/biomcp。

这会将 biomcp 二进制文件安装到 ~/.local/bin。如果该目录尚未加入 PATH，安装程序会打印一条用于添加该目录的命令；它绝不会修改你的 Shell 启动文件。

Homebrew

brew tap genomoncology/biomcp
brew install biomcp

必须先有单独的 genomoncology/homebrew-biomcp tap 仓库，这些命令才能正常运行。

Docker

docker run --rm ghcr.io/genomoncology/biomcp --version
docker run --rm ghcr.io/genomoncology/biomcp list
docker run --rm -i ghcr.io/genomoncology/biomcp serve

如需快速检查 CLI，或供无需本地安装的 stdio MCP 客户端使用，请使用 GHCR 镜像。

Claude Code 插件

先安装 biomcp 二进制文件，然后添加托管的插件市场，并在 Claude Code 中安装 BioMCP 插件：

/plugin marketplace add genomoncology/biomcp
/plugin install biomcp@biomcp

该插件通过 biomcp serve 将 Claude Code 连接到本地 stdio MCP 服务。如需使用 BioMCP 引导式工作流，也请安装下方的技能资源。

Codex MCP 服务

先安装 biomcp 二进制文件，然后向 Codex 注册相同的 stdio MCP 服务：

codex mcp add biomcp -- biomcp serve

Claude Desktop 扩展（.mcpb）

如果你的环境支持此方式，请在 Claude Desktop 的 Anthropic Directory 中安装 BioMCP。对于本地／手动设置，请使用下面的 JSON MCP 配置。

安装技能

可执行文件内置了指南和示例。运行 biomcp skill render 阅读完整指南，或将副本安装到你的 Agent 目录中：

biomcp skill install ~/.claude --force

MCP 客户端

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

远程 HTTP 服务

用于共享或远程部署：

biomcp serve-http --host 127.0.0.1 --port 8080

远程客户端连接到 http://127.0.0.1:8080/mcp。探测路由为 GET /health、GET /readyz 和 GET /。

可运行的演示：

uv run --script examples/streamable-http/streamable_http_client.py

请参阅远程 HTTP 服务的新手指南。

从源代码构建

make install
"$HOME/.local/bin/biomcp" --version

若要在仓库本地进行验证，请直接运行标准检查：make lint、make test 和 make spec。make test 包含 Rust nextest 和 Python／文档契约测试；make release-gate 则会额外运行指定的全功能验证，并使用启用所有功能的发布版二进制文件运行规格测试。 不支持 make check 命令。仅在选择进行实时公共上游验证时使用 make verify；make release-live-smoke 仍是兼容性别名。

命令语法

search <entity> [filters]    → discovery
skill list                   → playbook catalog for how-to questions
discover <query>             → concept resolution before entity selection
get <entity> <id> [sections] → focused detail
<entity> <helper> <id>       → cross-entity pivots
enrich <GENE1,GENE2,...>     → gene-set enrichment
batch <entity> <id1,id2,...> → parallel gets
search all [slot filters]    → counts-first cross-entity orientation

实体和数据源

下表区分详情卡实体与仅支持搜索的对象，避免 Agent 合成不受支持的 get 命令。

可获取的实体

Entity	BioMCP 使用的上游提供方	示例
gene	MyGene.info, UniProt, Reactome, QuickGO, STRING, GTEx, Human Protein Atlas, DGIdb, ClinGen, NIH Reporter, DisGeNET, GTR 支持的诊断关联查询	biomcp get gene BRAF pathways hpa
variant	MyVariant.info, ClinVar, gnomAD v4 直接人群数据, CIViC, Cancer Genome Interpreter, OncoKB, cBioPortal, GWAS Catalog, AlphaGenome	biomcp get variant "BRAF V600E" clinvar
article	PubMed, PubTator3, Europe PMC, PMC OA, NCBI ID Converter, Semantic Scholar（可选认证；建议设置 S2_API_KEY）	biomcp search article -g BRAF --limit 5
author	Semantic Scholar, ORCID	biomcp get author semanticscholar:1716151
trial	ClinicalTrials.gov API v2, NCI CTS API	biomcp search trial -c melanoma -s recruiting
diagnostic	NCBI Genetic Testing Registry 本地批量数据包 + WHO IVD 本地 CSV + 可选 OpenFDA 设备叠加数据	biomcp get diagnostic GTR000006692.3 regulatory
drug	MyChem.info, DDInter 本地数据包, EMA 本地批处理, WHO Prequalification 本地导出数据, ChEMBL, OpenTargets, Drugs@FDA, OpenFDA 标签／短缺／批准／FAERS／MAUDE／召回数据, CIViC	biomcp drug interactions warfarin
disease	MyDisease.info, Monarch Initiative, MONDO, OpenTargets, Reactome, CIViC, SEER Explorer, NIH Reporter, DisGeNET, GTR／WHO IVD 诊断关联查询	biomcp get disease "Lynch syndrome" genes
pathway	Reactome, KEGG, WikiPathways, g:Profiler, 基于 Enrichr 的富集部分	biomcp get pathway hsa05200 genes
protein	UniProt, InterPro, STRING, ComplexPortal, PDB, AlphaFold	biomcp get protein P15056 complexes
adverse-event	OpenFDA FAERS／MAUDE／召回数据，以及 CDC WONDER VAERS 疫苗汇总搜索	biomcp search adverse-event --drug pembrolizumab
pgx	CPIC, PharmGKB	biomcp get pgx CYP2D6 recommendations
cell-line	Cellosaurus，以及 ChEMBL、PharmacoDB、DepMap、COSMIC、GDSC 和 LINCS 交叉引用	biomcp get cell-line CVCL_0004 xrefs

仅支持搜索的实体

Entity	BioMCP 使用的上游提供方	示例
gwas	GWAS Catalog	biomcp search gwas --trait "type 2 diabetes"
phenotype	Monarch Initiative（HPO 语义相似度及直接支持检查）	biomcp search phenotype "HP:0001250"

跨实体辅助工具

在相关实体之间切换，无需重新构建筛选条件。

关于何时使用辅助工具而非重新搜索，请参阅跨实体切换指南。

biomcp variant trials "BRAF V600E" --limit 5
biomcp variant articles "BRAF V600E"
biomcp drug adverse-events pembrolizumab
biomcp drug trials pembrolizumab
biomcp disease trials melanoma
biomcp disease drugs melanoma
biomcp disease articles "Lynch syndrome"
biomcp gene trials BRAF
biomcp gene drugs BRAF
biomcp gene articles BRCA1
biomcp gene pathways BRAF
biomcp pathway drugs R-HSA-5673001
biomcp pathway drugs hsa05200
biomcp pathway articles R-HSA-5673001
biomcp pathway trials R-HSA-5673001
biomcp protein structures P15056
biomcp article entities 22663011
biomcp article citations 22663011 --limit 3
biomcp article references 22663011 --limit 3
biomcp article recommendations 22663011 --limit 3

基因集富集分析

biomcp enrich BRAF,KRAS,NRAS --limit 10

顶层命令 biomcp enrich 使用 g:Profiler。其他实体视图中的基因富集部分仍会在底层数据源为 Enrichr 时引用它。

分区与渐进式信息披露

每个 get 命令都支持选择分区，以便聚焦输出：

biomcp get gene BRAF                    # summary card
biomcp get gene BRAF pathways           # add pathway section
biomcp get gene BRCA1 diagnostics       # diagnostic-test pivot from GTR
biomcp get gene BRAF hpa                # protein tissue expression + localization
biomcp get gene BRAF civic interactions # multiple sections
biomcp get gene BRAF all                # standard sections; diagnostics/funding stay opt-in

biomcp get variant "BRAF V600E" clinvar population conservation
biomcp get article 22663011 tldr
biomcp get drug pembrolizumab label targets civic approvals
biomcp get drug trastuzumab regulatory --region who
biomcp get disease "Lynch syndrome" genes phenotypes variants
biomcp get disease tuberculosis diagnostics
biomcp get diagnostic GTR000006692.3 regulatory
biomcp get trial NCT02576665 eligibility locations outcomes

在 JSON 模式下，get 响应会通过 _meta.next_commands 提供后续最可能执行的命令，通过 _meta.section_sources 提供分区级来源信息。batch ... --json 会为每个实体返回具有相同元数据结构的对象。

API 密钥

大多数命令无需凭据即可使用。可选密钥可提高速率限制，或启用可选的富集功能：

export NCBI_API_KEY="..."        # ClinVar, PubTator, PubMed/efetch, PMC OA, NCBI ID converter
export S2_API_KEY="..."          # Optional Semantic Scholar auth; dedicated quota at 1 req/sec
export OPENFDA_API_KEY="..."     # OpenFDA rate limits
export NCI_API_KEY="..."         # NCI CTS trial search (--source nci)
export ONCOKB_TOKEN="..."        # OncoKB variant helper
export ALPHAGENOME_API_KEY="..." # AlphaGenome variant effect prediction

search article、get article、batch article、get article ... tldr 以及显式的 Semantic Scholar 辅助工具均可在没有 S2_API_KEY 的情况下使用。设置密钥后，BioMCP 会发送经过身份验证的请求，并使用专属速率限制，每秒 1 次请求。未设置密钥时，BioMCP 使用共享的未认证请求池，每 2 秒 1 次请求。search article --source 支持 all、pubtator、europepmc、pubmed、semanticscholar 和 litsense2。默认的兼容文章联合检索使用 PubTator3、Europe PMC、PubMed 和自动 Semantic Scholar；如果希望仅使用其中某个来源，请显式指定 --source semanticscholar 或 --source litsense2。显式选择来源还会禁用跨提供方的行级信息补充。由于 Semantic Scholar 上游覆盖范围内的出版商内容省略，付费墙论文可能没有参考文献和推荐内容。

配置

Claude Desktop 扩展设置

目录捆绑包仅公开首个面向审核者的构建所需的可选设置：

Claude Desktop 字段	运行时环境变量	用途
OncoKB Token	ONCOKB_TOKEN	启用 biomcp variant oncokb "<gene> <variant>" 的治疗与证据等级信息
DisGeNET API Key	DISGENET_API_KEY	启用基因和疾病查询中的 DisGeNET 评分分区
Semantic Scholar API Key	S2_API_KEY	提高文章 TLDR、引文、参考文献和推荐辅助工具的可靠性

首个目录构建仅公开这三个可选设置。仅限高级命令行使用的环境变量仍记录在API 密钥中，供通用 BioMCP 命令行使用。

使用示例

公开的跨实体概览

用户提示词： 请简要概览 BRAF 与黑色素瘤，尽量减少噪声。

预期工具调用： biomcp search all --gene BRAF --disease melanoma --counts-only

预期行为： 返回跨实体计数摘要，为下一条命令提供方向，而非倾倒冗长的详细表格。

预期输出： 以计数为先的摘要，并建议后续最有价值的实体查询命令。

公开的变异证据

用户提示词： 请汇总 BRAF V600E 的 ClinVar 临床意义和人群频率。

预期工具调用： biomcp get variant "BRAF V600E" clinvar population

预期行为： 通过一次只读调用获取聚焦的变异卡片、ClinVar 分区和人群频率数据。

预期输出： 变异摘要、ClinVar 临床意义详情，以及 gnomAD 人群频率。

需要凭据的 OncoKB 示例

用户提示词： 请展示 BRAF V600E 的 OncoKB 治疗证据。

预期工具调用： biomcp variant oncokb "BRAF V600E"

预期行为： 配置了 ONCOKB_TOKEN 时使用该变量；否则会针对缺少的凭据提供有帮助的说明。

预期输出： 设置了 ONCOKB_TOKEN 时提供治疗与证据等级信息；否则给出明确的设置提示。

带凭据的 DisGeNET 示例

用户提示： 显示 TP53 的 DisGeNET 关联评分。

预期工具调用： biomcp get gene TP53 disgenet

预期行为： 使用 DISGENET_API_KEY 检索带评分的基因-疾病关联部分。

预期输出： 配置了 DISGENET_API_KEY 时，显示包含证据数量和评分的疾病关联排名表。

隐私政策

BioMCP 不会添加遥测、分析功能或远程日志上传。请在 https://biomcp.org/policies/ 查看完整隐私声明。

多工作进程部署

BioMCP 的速率限制仅在进程内生效。若有许多并发工作进程，请运行一个共享的 Streamable HTTP biomcp serve-http 端点，让所有工作进程共享同一个限流额度：

biomcp serve-http --host 0.0.0.0 --port 8080 \
  --allowed-hosts biomcp.example.org

默认情况下，环回服务器只接受本地 Host 值。非环回绑定需要使用 --allowed-hosts。显式使用 --unsafe-allow-any-host 绕过限制，只会禁用此 Host 检查；它不会添加身份验证、TLS 或加密。请将远程部署置于可信的、经过身份验证的 TLS 代理之后，或放在专用网络内。

远程客户端应连接到 http://<host>:8080/mcp。可通过 GET /health、GET /readyz 和 GET / 进行轻量级进程探测。

Skills

BioMCP 内置了 Agent 指南和实用示例目录。 需要合适的实用示例时，请使用 biomcp skill list，然后使用 biomcp skill 阅读内置的 BioMCP 指南，或将其安装到你的 Agent 目录，以便在需要时获取工作流参考的本地副本：

biomcp skill list
biomcp skill
biomcp skill install ~/.claude --force

支持的安装目标、已安装文件和旧版兼容性说明，请参阅 Skills。

本地研究分析

study 是 BioMCP 针对已下载的 cBioPortal 风格数据集提供的本地分析命令系列。公共实体接口支持基于 API、本地运行时和混合模式的发现与详情查询；需要按研究进行查询、队列、生存分析、比较或共现工作流时，可使用针对本地数据集的 study 命令。按基因查询时，可从本地 data_sv.txt 文件获取突变、CNA、表达和结构变异/融合信息。突变摘要仅包含突变，并会注明融合/SV 需要使用 --type sv。

使用 study download 将数据集下载到本地研究根目录。若要为可复现脚本和演示指定明确的数据集位置，请设置 BIOMCP_STUDY_DIR；如果未设置，BioMCP 将使用默认研究根目录。

export BIOMCP_STUDY_DIR="$HOME/.local/share/biomcp/studies"
biomcp study download msk_impact_2017
biomcp study query --study msk_impact_2017 --gene TP53 --type mutations --chart bar --theme dark --palette wong -o docs/blog/images/tp53-mutation-bar.svg
biomcp study query --study msk_impact_2017 --gene RET --type sv

完整的 study 命令系列和数据集前置条件，请参阅 CLI 参考。

运维

biomcp version                            # show version and build info
biomcp health                             # inspect API connectivity plus local DDInter/EMA/cache readiness
biomcp update                             # self-update with release SHA256 checksum verification
biomcp update --check                     # check for updates without installing
biomcp uninstall                          # remove biomcp from ~/.local/bin

支持

• GitHub 问题：https://github.com/genomoncology/biomcp/issues
• 故障排除：docs/troubleshooting.md
• 完整文档：https://biomcp.org/

文档

• 入门指南
• 全流程搜索
• BioASQ 基准测试
• 跨实体透视指南
• 隐私政策
• 来源许可与条款
• 数据源
• 快速参考
• 故障排除

引用

如果你在研究中使用 BioMCP，请通过 CITATION.cff 引用。存在该文件时，GitHub 也会在仓库侧边栏中显示 Cite this repository。

数据源与许可

BioMCP 采用 MIT 许可。它会按需向上游提供方查询，而不会随项目分发或镜像其数据集，但上游条款决定了检索结果的再利用方式。

有些提供方完全开放，有些 BioMCP 功能需要注册或 API 密钥，还有些可查询的数据源仍对再利用设有显著限制。需要特别注意的两项是 KEGG（区分学术用途和非学术用途）和 COSMIC（由于其许可模式与直接开放集成不兼容，BioMCP 仅以间接方式提供）。

各数据源的具体说明请参阅 数据源许可与条款；设置步骤和注册链接请参阅 API 密钥。

许可证

MIT