PubTator MCP Server

PubTator MCP Server

🔍 一个基于 PubTator3 的生物医学文献标注和关系挖掘服务，通过 MCP 接口提供便捷访问。

PubTator MCP Server 通过 Model Context Protocol（MCP）为 AI 助手提供对 PubTator3 生物医学文献标注系统的访问。它允许 AI 模型以编程方式搜索科学文献、获取标注信息并分析实体关系。

🤝 参与贡献 • 📝 报告问题

✨ 核心功能

• 🔎 文献标注导出：支持以多种格式导出 PubTator 标注结果 ✅
• 🚀 实体 ID 查询：通过自由文本查询生物概念的标准标识符 ✅
• 📊 关系挖掘：发现实体间的生物医学关系 ✅
• 📄 文献搜索：支持按关键词和实体 ID 检索文献 ✅
• 🧠 批量处理：支持批量导出搜索结果中的标注信息 ✅

🚀 快速开始

要求

• Python 3.10+
• FastMCP 库

安装

通过 Smithery 安装

使用 Smithery 自动安装 PubTator Server：

Claude

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

Cursor

粘贴到 Settings → Cursor Settings → MCP → Add new server：

• Mac/Linux

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

Windsurf

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

CLine

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

手动安装

1. 克隆仓库：

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

2. 安装依赖：

   pip install -r requirements.txt
   

📊 使用方法

直接运行服务

启动 MCP 服务：

python pubtator_server.py

该服务现在同时支持 stdio 和 TCP 传输方式。默认使用 TCP 传输。你可以配置以下环境变量：

• MCP_TRANSPORT：设为 "tcp" 使用 TCP 传输，或设为 "stdio" 使用 stdio 传输（默认值为 "tcp"）
• MCP_HOST：要绑定的主机（默认值为 "0.0.0.0"）
• MCP_PORT：要监听的端口（默认值为 8080）

使用自定义设置启动服务的示例：

MCP_TRANSPORT=tcp MCP_HOST=127.0.0.1 MCP_PORT=8888 python pubtator_server.py

该服务实现了延迟初始化和适当的错误处理。它会妥善处理关闭信号（SIGINT 和 SIGTERM），并记录启动或运行期间发生的任何错误。

使用 Docker

我们提供了一个 Dockerfile，便于部署。使用 Docker 容器的步骤如下：

1. 构建 Docker 镜像：

   docker build -t pubtator-mcp-server .
   

2. 运行 Docker 容器：

   docker run -p 8080:8080 pubtator-mcp-server
   

这将在 Docker 容器中启动 PubTator MCP 服务，并通过 8080 端口对外提供服务。

故障排除

如果启动服务时遇到问题：

1. 检查控制台输出中的错误消息。
2. 确认已安装所有必需的依赖项（参见“要求”部分）。
3. 确认环境变量设置正确。
4. 如果服务无法启动，请尝试增加详细程度后运行：

python -v pubtator_server.py

这将提供更详细的日志信息，帮助确定问题来源。

使用 Docker 时，可以通过以下命令查看日志：

docker logs <container_id>

配置

Claude Desktop 配置

添加到 claude_desktop_config.json：

（Mac OS）

{
  "mcpServers": {
    "pubtator": {
      "command": "python",
      "args": ["-m", "pubtator-mcp-server"]
      }
  }
}

（Windows）

{
  "mcpServers": {
    "pubtator": {
      "command": "C:\\Users\\YOUR\\PATH\\miniconda3\\envs\\mcp_server\\python.exe",
      "args": [
        "D:\\code\\YOUR\\PATH\\PubTator-MCP-Server\\pubtator_server.py"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

CLine 配置

{
  "mcpServers": {
    "pubtator": {
      "command": "bash",
      "args": [
        "-c",
        "source /home/YOUR/PATH/mcp-server-pubtator/.venv/bin/activate && python /home/YOUR/PATH/pubtator_server.py"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

要使用 TCP 传输，请按如下方式修改配置：

{
  "mcpServers": {
    "pubtator": {
      "command": "bash",
      "args": [
        "-c",
        "source /home/YOUR/PATH/mcp-server-pubtator/.venv/bin/activate && python /home/YOUR/PATH/pubtator_server.py"
      ],
      "env": {
        "MCP_TRANSPORT": "tcp",
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "8888"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

🛠 API 功能

PubTator MCP Server 提供以下核心功能：

1. 导出文献（export_publications）

导出指定 PMID 文献的 PubTator 标注结果：

result = await export_publications(
    ids=["32133824", "34170578"],
    id_type="pmid",
    format="biocjson",  # Supported: pubtator, biocxml, biocjson
    full_text=False     # Whether to include full text
)

2. 实体 ID 查询（find_entity_id）

通过自由文本查询生物概念的标准标识符：

result = await find_entity_id(
    query="COVID-19",
    concept="disease",  # Optional: gene, disease, chemical, species, mutation
    limit=5             # Optional: limit number of results
)

3. 关系查询（find_related_entities）

查找与指定实体相关的其他实体：

result = await find_related_entities(
    entity_id="@DISEASE_COVID_19",
    relation_type="treat",    # Optional: treat, cause, interact, etc.
    target_entity_type="chemical",  # Optional: gene, disease, chemical
    max_results=5       # Optional: limit number of results
)

4. 文献搜索（search_pubtator）

搜索 PubTator 数据库：

results = await search_pubtator(
    query="COVID-19",
    max_pages=1     # Optional: maximum number of pages to retrieve
)

5. 批量导出（batch_export_from_search）

搜索并批量导出文献注释：

results = await batch_export_from_search(
    query="COVID-19",
    format="biocjson",
    max_pages=1,
    full_text=False,
    batch_size=5
)

注意：实际的函数调用可能因实现方式而异。这些示例基于我们最近的测试，可能需要调整以匹配你的确切 API。

⚠️ 使用限制

• API 请求速率限制：每秒最多 3 个请求
• 批量导出时，请使用合理的 batch_size，以避免请求超时
• 对于关系查询，实体 ID 必须以「@」开头，例如「@DISEASE_COVID-19」

📄 许可证

本项目采用 MIT 许可证。

⚠️ 免责声明

此工具仅供研究使用。请遵守 PubTator 的服务条款，并负责任地使用此工具。