██████╗ ██╗   ██╗██████╗ ███╗   ███╗███████╗██████╗     ██████╗  █████╗ ████████╗ █████╗
██╔══██╗██║   ██║██╔══██╗████╗ ████║██╔════╝██╔══██╗   ██╔════╝ ██╔══██╗╚══██╔══╝██╔══██╗
██████╔╝██║   ██║██████╔╝██╔████╔██║█████╗  ██║  ██║   ██║  ███╗███████║   ██║   ███████║
██╔═══╝ ██║   ██║██╔══██╗██║╚██╔╝██║██╔══╝  ██║  ██║   ██║   ██║██╔══██║   ██║   ██╔══██║
██║     ╚██████╔╝██████╔╝██║ ╚═╝ ██║███████╗██████╔╝   ╚██████╔╝██║  ██║   ██║   ██║  ██║
╚═╝      ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚══════╝╚═════╝     ╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝

PubMed Data Server v2.0

为 LLM 提供结构化 PubMed 文献数据的 MCP 服务器。专注数据提供，分析交给 LLM。

用户客户端(LLM) ←→ MCP服务器(数据获取+结构化) ←→ PubMed API

核心能力： 文献搜索 / 智能缓存 / OA 全文下载 / EndNote 导出（RIS + BibTeX）

快速开始

前置要求： Node.js v18.0.0+

1. 安装

# npm 全局安装（推荐）
npm install -g mcp-pubmed-llm-server

# 或从源码安装
git clone git@github.com:PancrePal-xiaoyibao/mcp-pubmed-server-pancrpal.git
cd mcp-pubmed-server-pancrpal && npm install

2. 配置 API 密钥

cp .env.example .env

编辑 .env，填入配置：

PUBMED_API_KEY=你的NCBI_API密钥    # 可选，https://www.ncbi.nlm.nih.gov/account/settings/
PUBMED_EMAIL=你的邮箱地址            # 可选（建议填写）

说明： API Key 和 Email 均非必填。无 Key 时以匿名模式运行（限速 3 次/秒），有 Key 时提升至 10 次/秒。

多 API Key 池（可选）： 支持多个 Key 轮询/主备/随机负载均衡，参见下方 API Key 池配置 章节。

可选配置：

ABSTRACT_MODE=quick       # quick(1500字符) | deep(6000字符)
FULLTEXT_MODE=disabled    # disabled | enabled | auto
ENDNOTE_EXPORT=enabled    # enabled | disabled

3. 运行

# npm 包
mcp-pubmed-llm-server
# 或
npx mcp-pubmed-llm-server

# 源码
node src/index.js

传输模式

服务器支持两种传输模式，适用于不同场景：

stdio 模式（默认）

通过标准输入输出与 MCP 客户端通信，无需配置端口。

node src/index.js --mode=stdio
# 或
npm run start:stdio

Streamable HTTP 模式（服务端部署）

MCP 2025-11-25 规范推荐的 HTTP 传输方式，统一的 /mcp 端点 + 会话管理。适用于 Cherry Studio 等远程 MCP 客户端。默认端口 8745。

方式一：直接运行

node src/index.js --mode=streamableHttp
# 或
npm run start:streamableHttp

方式二：Docker 部署

cd docker
cp .env.example .env
# 编辑 .env，填入 PUBMED_API_KEY 和 PUBMED_EMAIL（均为可选）

docker compose up -d --build

验证：

curl http://localhost:8745/health
# {"status":"ok","mode":"streamableHttp","sessions":0}

端点：

• POST /mcp — JSON-RPC（首次必须为 initialize，返回 Mcp-Session-Id）
• GET /mcp — 服务器事件流（带 Mcp-Session-Id）
• DELETE /mcp — 关闭会话
• GET /health — 健康检查

反向代理（Nginx 示例）：

location / {
    proxy_pass http://127.0.0.1:8745;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_read_timeout 3600;
    proxy_send_timeout 3600;
    proxy_buffering off;              # 必须禁用缓冲
    add_header X-Accel-Buffering no;
}

生产环境建议：

• 使用进程管理器（PM2、systemd）确保持续运行
• 配置 HTTPS 反向代理
• 设置防火墙规则，仅开放必要端口

MCP 客户端配置

Cline / Claude Desktop / Claude Code

stdio 模式（本地运行）：

{
  "mcpServers": {
    "pubmed-data-server": {
      "command": "npx",
      "args": ["-y", "mcp-pubmed-llm-server"],
      "env": {
        "PUBMED_API_KEY": "你的API密钥（可选）",
        "PUBMED_EMAIL": "你的邮箱地址（可选）",
        "ABSTRACT_MODE": "deep",
        "FULLTEXT_MODE": "enabled"
      }
    }
  }
}

说明： PUBMED_API_KEY 和 PUBMED_EMAIL 均为可选。不填则以匿名模式运行（限速 3 次/秒），填写后提升至 10 次/秒。如需多 Key 池，参见 API Key 池配置。

配置文件位置：

• Cline: VS Code 设置中的 MCP Servers 配置
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%/Claude/claude_desktop_config.json (Windows)
• Claude Code: ~/.claude/config.json

也可使用 "command": "mcp-pubmed-llm-server"（全局安装后）或 "command": "node", "args": ["/path/to/src/index.js"]（源码安装）。

Cherry Studio

stdio 模式：

{
  "mcpServers": {
    "pubmed-data-server": {
      "name": "pubmed-data-server",
      "type": "stdio",
      "isActive": true,
      "command": "npx",
      "args": ["-y", "mcp-pubmed-llm-server"],
      "env": {
        "PUBMED_API_KEY": "你的API密钥（可选）",
        "PUBMED_EMAIL": "你的邮箱地址（可选）"
      }
    }
  }
}

streamableHttp 模式（远程部署）：

• type: streamableHttp
• baseUrl: http://<服务器IP>:8745/mcp

Cherry Studio 不支持 cwd 参数。Windows 路径使用正斜杠 / 或双反斜杠 \\。

工具列表

共 13 个 MCP 工具：

文献搜索

缓存管理

全文下载（需 FULLTEXT_MODE=enabled）

EndNote 导出（需 ENDNOTE_EXPORT=enabled）

API Key 池配置

支持多个 NCBI API Key 的轮询、主备切换和随机负载均衡，提高并发能力和容错性。

配置方式

方式一：api-keys.json 文件（多 Key，推荐）

在项目根目录创建 api-keys.json（参见 api-keys.json.example）：

{
  "keys": [
    {
      "api_key": "你的第一个NCBI_API密钥",
      "email": "user1@example.com"
    },
    {
      "api_key": "你的第二个NCBI_API密钥",
      "email": "user2@example.com"
    }
  ],
  "strategy": "round-robin"
}

方式二：环境变量（单 Key，向后兼容）

PUBMED_API_KEY=你的NCBI_API密钥
PUBMED_EMAIL=你的邮箱地址

方式三：无 Key（匿名模式）

不配置任何 Key，以匿名模式运行（限速 3 次/秒）。

优先级： api-keys.json > 环境变量 > 匿名模式

Key 选择策略

健康管理

• 连续 3 次失败自动标记为不可用
• 60 秒冷却后自动恢复
• 所有 Key 不可用时强制恢复最早失败的 Key
• 通过 pubmed_system_check 工具可查看 Key 池状态

项目结构

mcp-pubmed-server/
├── src/
│   ├── index.js                # 入口点
│   ├── config.js               # 配置常量
│   ├── server.js               # 主编排器
│   ├── api/
│   │   ├── pubmed-client.js    # PubMed API 客户端
│   │   └── key-pool.js         # API Key 号池管理器
│   ├── cache/
│   │   ├── memory-cache.js     # 内存 LRU 缓存
│   │   └── file-cache.js       # 文件持久化缓存
│   ├── services/
│   │   ├── fulltext.js         # OA 检测 + PDF 下载
│   │   ├── endnote.js          # RIS / BibTeX 导出
│   │   └── system.js           # 系统环境检测
│   ├── tools/
│   │   ├── definitions.js      # 工具 schema 定义
│   │   └── handlers.js         # 工具调用路由
│   ├── transport/
│   │   ├── stdio.js            # stdio 传输
│   │   └── streamable-http.js  # Streamable HTTP 传输
│   └── utils/
│       └── formatter.js        # LLM 格式化
├── docker/                     # Docker 部署
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── .env.example
├── docs/
│   ├── FULLTEXT_SMART_DOWNLOAD.md
│   ├── ENDNOTE_EXPORT.md
│   └── GITHUB_ACTIONS_PUBLISH.md
├── api-keys.json.example       # 多 Key 池配置模板
├── .env.example
├── package.json
├── LICENSE
└── README.md

故障排除

npm 包

• 包名: mcp-pubmed-llm-server
• 安装: npm install -g mcp-pubmed-llm-server
• 使用: npx mcp-pubmed-llm-server 或 mcp-pubmed-llm-server

详细文档

• 全文下载与智能下载系统
• EndNote 导出功能
• GitHub Actions 自动发布

许可证

Apache License 2.0