PubTator MCP 服务器

smithery 徽章

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

PubTator MCP服务器通过模型上下文协议(MCP)为AI助手提供访问PubTator3生物医学文献标注系统的能力。它允许AI模型以编程方式搜索科学文献、获取标注信息并分析实体关系。

🤝 贡献 • 📝 报告问题

✨ 核心功能

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

🚀 快速开始

系统要求

Python 3.10+
FastMCP库

安装

通过Smithery安装

使用Smithery自动安装PubTator服务器：

Claude

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

Cursor

在设置→Cursor设置→MCP→添加新服务器中粘贴：

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 "{}"

手动安装

克隆仓库：

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

安装依赖：
```
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容器：

构建Docker镜像：
```
docker build -t pubtator-mcp-server .
```

运行Docker容器：

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

这将在Docker容器内启动PubTator MCP服务器，并在8080端口上暴露服务。

故障排除

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

检查控制台输出中的错误信息。
确保所有必需的依赖项已安装（参见"系统要求"部分）。
验证环境变量是否设置正确。
如果服务器启动失败，尝试以更高的详细程度运行：

python -v pubtator_server.py

这将提供更详细的日志信息以帮助识别问题的根源。

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

docker logs <容器ID>

配置

Claude桌面配置

添加到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服务器提供以下核心功能：

1. 导出文献（export_publications）

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

result = await export_publications(
    ids=["32133824", "34170578"],
    id_type="pmid",
    format="biocjson",  # 支持：pubtator, biocxml, biocjson
    full_text=False     # 是否包含全文
)

2. 实体ID查询（find_entity_id）

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

result = await find_entity_id(
    query="COVID-19",
    concept="disease",  # 可选：gene, disease, chemical, species, mutation
    limit=5             # 可选：限制结果数量
)

3. 关系查询（find_related_entities）

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

result = await find_related_entities(
    entity_id="@DISEASE_COVID_19",
    relation_type="treat",    # 可选：treat, cause, interact, 等
    target_entity_type="chemical",  # 可选：gene, disease, chemical
    max_results=5       # 可选：限制结果数量
)

4. 文献检索（search_pubtator）

搜索PubTator数据库：

results = await search_pubtator(
    query="COVID-19",
    max_pages=1     # 可选：要检索的最大页数
)

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的服务条款并负责任地使用本工具。