内容
# PubTator MCP 服务器
[](https://smithery.ai/server/@JackKuo666/pubtator-mcp-server)
🔍 一个基于 PubTator3 的生物医学文献注释和关系挖掘服务器，通过 MCP 接口提供便捷访问。
PubTator MCP 服务器通过模型上下文协议（MCP）为 AI 助手提供对 PubTator3 生物医学文献注释系统的访问。它允许 AI 模型以编程方式搜索科学文献、获取注释信息和分析实体关系。
🤝 贡献 • 📝 报告问题
## ✨ 核心功能
- 🔎 文献注释导出：支持以多种格式导出 PubTator 注释结果 ✅
- 🚀 实体 ID 查询：通过自由文本查询生物概念的标准标识符 ✅
- 📊 关系挖掘：发现实体之间的生物医学关系 ✅
- 📄 文献搜索：支持按关键词和实体 ID 检索文献 ✅
- 🧠 批量处理：支持批量导出搜索结果的注释信息 ✅
## 🚀 快速开始
### 要求
- Python 3.10+
- FastMCP 库
### 安装
#### 通过 Smithery
使用 [Smithery](https://smithery.ai/server/@JackKuo666/pubtator-mcp-server) 自动安装 PubTator 服务器：
##### Claude
```sh
npx -y @smithery/cli@latest install @JackKuo666/pubtator-mcp-server --client claude --config "{}"
```
##### Cursor
在设置 → Cursor 设置 → MCP → 添加新服务器中粘贴：
- Mac/Linux
```s
npx -y @smithery/cli@latest run @JackKuo666/pubtator-mcp-server --client cursor --config "{}"
```
##### Windsurf
```sh
npx -y @smithery/cli@latest install @JackKuo666/pubtator-mcp-server --client windsurf --config "{}"
```
##### CLine
```sh
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 服务器：
```bash
python pubtator_server.py
```
服务器现在支持 stdio 和 TCP 传输。默认情况下，它使用 TCP 传输。您可以配置以下环境变量：
- `MCP_TRANSPORT`：设置为 "tcp" 表示 TCP 传输或 "stdio" 表示 stdio 传输（默认为 "tcp"）
- `MCP_HOST`：要绑定的主机（默认为 "0.0.0.0"）
- `MCP_PORT`：要监听的端口（默认为 8080）
使用自定义设置启动服务器的示例：
```bash
MCP_TRANSPORT=tcp MCP_HOST=127.0.0.1 MCP_PORT=8888 python pubtator_server.py
```
服务器实现了惰性初始化和适当的错误处理。它将优雅地处理关闭信号（SIGINT 和 SIGTERM）并记录启动或运行时出现的任何错误。
### 使用 Docker
我们提供了一个 Dockerfile 以便于部署。要使用 Docker 容器：
1. 构建 Docker 镜像：
```bash
docker build -t pubtator-mcp-server .
```
2. 运行 Docker 容器：
```bash
docker run -p 8080:8080 pubtator-mcp-server
```
这将在 Docker 容器中启动 PubTator MCP 服务器，并在端口 8080 上公开它。
### 故障排除
如果您在启动服务器时遇到任何问题：
1. 检查控制台输出中的错误消息。
2. 确保已安装所有必需的依赖项（请参见要求部分）。
3. 验证环境变量是否设置正确。
4. 如果服务器无法启动，请尝试以更高的详细程度运行它：
```bash
python -v pubtator_server.py
```
这将提供更详细的日志信息，以帮助识别任何问题的源头。
使用 Docker 时，您可以使用以下命令检查日志：
```bash
docker logs <container_id>
```
### 配置
#### Claude Desktop 配置
添加到 `claude_desktop_config.json`：
（Mac OS）
```json
{
"mcpServers": {
"pubtator": {
"command": "python",
"args": ["-m", "pubtator-mcp-server"]
}
}
}
```
（Windows）
```json
{
"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 配置
```json
{
"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 传输，请按如下方式修改配置：
```json
{
"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 注释结果：
```python
result = await export_publications(
ids=["32133824", "34170578"],
id_type="pmid",
format="biocjson", # 支持：pubtator, biocxml, biocjson
full_text=False # 是否包含全文
)
```
### 2. 实体 ID 查询（find_entity_id）
通过自由文本查询生物概念的标准标识符：
```python
result = await find_entity_id(
query="COVID-19",
concept="disease", # 可选：gene, disease, chemical, species, mutation
limit=5 # 可选：限制结果数量
)
```
### 3. 关系查询（find_related_entities）
查找与指定实体相关的其他实体：
```python
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 数据库：
```python
results = await search_pubtator(
query="COVID-19",
max_pages=1 # 可选：要检索的最大页数
)
```
### 5. 批量导出（batch_export_from_search）
搜索并批量导出文献注释：
```python
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 的服务条款并负责任地使用本工具。
MCP 市场