PubTator-MCP-Server

在生物医学领域，每天都有海量的研究论文发表。对于研究人员、临床医生或药物开发者来说，从这些浩如烟海的文献中快速找到特定基因、疾病或化学物质之间的已知关系，往往需要花费数小时甚至数天的时间筛选和阅读。如果能让 AI 助手直接帮你挖掘这些文献中的宝藏，效率将会得到质的飞跃。

PubTator-MCP-Server 正是为此而生的工具。它是一个基于模型上下文协议（MCP）的服务器，专门连接 NCBI 的 PubTator3 系统。PubTator3 是一个对 PubMed 中央文献进行自动标注的系统，它能够识别出文中提到的基因、疾病、化学物质、物种等生物医学实体及其相互关系。通过这个 MCP 服务器，你可以让 AI 助手直接搜索文献、获取实体的标准化 ID、甚至挖掘实体之间的关系。

项目基本信息

一、项目介绍

PubTator-MCP-Server 是一个用 Python 编写的 MCP 服务器，它封装了 PubTator3 的 API，并向 AI 客户端暴露了五个核心工具。PubTator3 本身是 NCBI 提供的一个服务，它会自动阅读生物医学论文，并标记出其中重要的生物概念。

这个服务器让你可以通过自然语言完成以下专业任务：

• 导出文献标注：根据 PMID 获取某篇论文中所有被标注的实体。
• 查找实体 ID：输入一个生物词汇，获取其在 MeSH、Gene 等数据库中的标准 ID。
• 关系挖掘：给定一个实体，找出与之相关的其他实体及其关系类型。
• 文献搜索：通过关键词在 PubTator 中检索相关论文。
• 批量导出：搜索并批量导出多篇论文的标注结果。

该服务器支持 stdio 和 TCP 两种传输方式，并提供了完整的 Docker 支持，可以轻松部署在任何环境中。

二、核心优势

零门槛访问专业生物医学数据
你不需要了解 PubTator 的 API 细节、数据格式或认证方式。只需要用中文或英文提问，AI 会帮你调用正确的工具。

五种专业工具，覆盖核心需求
从简单的搜索到复杂的关系挖掘，五个工具形成了一个完整的发现链条。无论是想快速了解某个基因的相关文献，还是想探索疾病与药物的关联，都有对应的工具。

支持批量操作与多种格式
export_publications 和 batch_export_from_search 支持批量处理，并且可以输出 pubtator、biocxml、biocjson 三种格式，方便与其他生物信息学工具链集成。

灵活的部署方式
项目支持通过 Smithery 一键安装到 Claude、Cursor、Windsurf 等客户端，也支持手动克隆安装。同时提供 Docker 镜像，可以在服务器上以 TCP 模式运行，供团队共享使用。

注意 API 使用限制
项目文档明确提到 API 请求速率限制为每秒最多 3 次。这个透明性很好，让你可以合理规划批量任务的规模，避免被封禁。

三、适用场景

药物重定位研究
你可以问 AI：“找出与‘COVID-19’相关的化学物质中，有哪些是已知的抗病毒药物。” AI 会调用关系查询工具，从文献中挖掘出潜在的药物候选。

基因功能注释
当你研究一个新发现的基因时，可以问：“搜索包含‘BRCA1’的文献，并导出这些文献中与该基因共同出现的疾病类型。” 这有助于快速理解基因的功能。

系统综述的文献筛选
在进行系统综述或 Meta 分析时，你需要从大量文献中提取特定信息。你可以让 AI 批量导出搜索结果的标注，然后进行后续分析。

教学与科普
在生物医学课堂上，教师可以实时演示：“查找‘糖尿病’的标准 MeSH ID”，或者“展示‘胰岛素’与‘葡萄糖’在文献中的共现关系”。

构建领域知识图谱
利用批量导出和关系挖掘能力，你可以构建一个小型的基因-疾病-药物关系知识图谱，用于后续的图分析或可视化。

四、安装教程

安装 PubTator-MCP-Server 有多种方式。推荐使用 Smithery 进行一键安装，也可以手动安装以获得最大控制权。

方法一：通过 Smithery 安装到 Claude Desktop

这是最简单快捷的方式。确保你已安装 Node.js 并关闭了 Claude Desktop。在终端中运行：

npx -y @smithery/cli@latest install @JackKuo666/pubtator-mcp-server --client claude --config "{}"

等待命令执行完毕，然后重新启动 Claude Desktop。在对话界面右侧应能看到新工具。

方法二：手动克隆与安装

如果你希望获得源代码，或需要安装到其他 MCP 客户端，请执行以下步骤。

第一步：克隆仓库

git clone https://github.com/JackKuo666/PubTator-MCP-Server.git
cd PubTator-MCP-Server

第二步：安装依赖

项目推荐使用 Python 3.10 或以上版本。你可以创建一个虚拟环境（推荐）来隔离依赖。

python -m venv venv
source venv/bin/activate  # 在 Windows 上使用 venv\Scripts\activate
pip install -r requirements.txt

第三步：配置 MCP 客户端

对于 Claude Desktop，编辑其配置文件（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json；Windows: %AppData%\Claude\claude_desktop_config.json），添加以下内容，并将 Python 路径和脚本路径替换为你的实际路径。

{
  "mcpServers": {
    "pubtator": {
      "command": "/你的Python虚拟环境路径/bin/python",
      "args": ["/你的克隆路径/PubTator-MCP-Server/pubtator_server.py"]
    }
  }
}

对于 Cursor IDE，在设置中找到 MCP 部分，添加一个新的命令服务器，使用相同的 command 和 args。

第四步：启动并测试

重启客户端后，你可以问一个简单的问题来测试，例如：“请帮我查找‘COVID-19’作为疾病的实体 ID。”

五、使用示例

假设你已经通过 Smithery 或手动方式配置好了服务器，以下是在 Claude 中实际对话的例子。

示例1：查找实体的标准 ID

用户输入：帮我查一下“白介素-6”作为基因的实体 ID 是什么。

Claude 会调用 find_entity_id 工具，参数为 query: "白介素-6", concept: "gene"。然后它会返回类似 "@GENE_IL6" 这样的标准 ID，并可能解释这个 ID 对应的官方基因名称。

示例2：根据 PMID 导出文献标注

用户输入：请导出 PMID 为 32133824 和 34170578 这两篇文献的 PubTator 标注结果，格式用 biocjson。

Claude 会调用 export_publications 工具，返回这两篇论文中所有被标注的基因、疾病、化学物质等信息，并以 JSON 格式呈现。

示例3：挖掘实体之间的关系

用户输入：对于疾病实体 @DISEASE_COVID_19，找到与之相关的化学物质，特别是那些被标注为“治疗”关系的。

Claude 会调用 find_related_entities 工具，参数为 entity_id: "@DISEASE_COVID_19", relation_type: "treat", target_entity_type: "chemical"。它会返回一系列可能与 COVID-19 治疗相关的药物或化合物。

示例4：搜索并批量导出

用户输入：搜索关键词“CRISPR”，导出第一页搜索结果的标注，格式用 pubtator。

Claude 会先使用 search_pubtator 找到相关文献的 PMID 列表，然后调用 batch_export_from_search 或循环调用 export_publications，最终返回多篇文献的标注汇总。

六、常见问题

问题1：使用 Smithery 安装后，Claude Desktop 中看不到 PubTator 工具。

解决方案：请确保你在运行安装命令前，完全退出了 Claude Desktop（包括系统托盘图标）。安装完成后，手动启动 Claude。如果问题依旧，可能是因为 macOS 的安全策略，可以尝试手动安装方法。

问题2：运行 pubtator_server.py 时提示缺少依赖或模块。

解决方案：请确认你已经激活了正确的 Python 虚拟环境，并完整执行了 pip install -r requirements.txt。如果仍然报错，尝试重新生成 requirements.txt：pip freeze > requirements.txt，然后再次安装。

问题3：查询关系时返回结果为空，即使我认为存在已知关系。

解决方案：PubTator3 的标注覆盖范围有限，并非所有文献中的所有关系都会被标注。另外，请确保你使用的实体 ID 格式正确，必须以 @ 开头，例如 @DISEASE_COVID_19。关系类型参数（如 treat、cause）也可能区分大小写，建议参考 PubTator 官方文档。

问题4：批量导出时很慢或超时。

解决方案：这是正常的，因为 PubTator API 有每秒 3 次的速率限制。请减小 batch_size 参数（例如设为 5），或者减少 max_pages。你也可以考虑在非高峰时段运行批量任务，或者将服务器部署到网络延迟较低的环境。

问题5：这个服务器是否需要 NCBI API 密钥？

解决方案：目前看起来不需要。项目使用的是 PubTator3 的公开 API 端点，没有强制要求 API 密钥。但公开接口有严格的速率限制，请合理使用。如果需要更高频率的访问，你可能需要自行申请 NCBI API 密钥并修改代码。

七、总结

PubTator-MCP-Server 是一个将专业生物医学文献挖掘能力带给 AI 的桥梁项目。它精巧地将 PubTator3 的复杂 API 封装成了五个直观的 MCP 工具，让研究人员和开发者可以用最自然的对话方式，从海量文献中提取基因、疾病、药物之间的关系。

这个项目的价值不仅在于它本身的功能，更在于它展示了一种模式：任何拥有丰富科研数据的领域，都可以通过类似的 MCP 服务器，让 AI 成为该领域的智能检索与分析助理。对于生物信息学、药物研发、医学教育等领域的从业者来说，这个工具可以大幅减少文献筛选的重复劳动。

该项目采用 MIT 许可证，代码清晰，文档详尽，并提供了 Smithery、Docker 等多种部署方式。无论你是需要实际使用的科研人员，还是希望学习如何构建数据密集型 MCP 服务器的开发者，PubTator-MCP-Server 都是一个值得尝试和研究的优秀范例。