Mcp Pubmed Server

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

[](LICENSE) [](https://github.com/your-repo/mcp-pubmed-server) [](https://modelcontextprotocol.io/) [](https://www.ncbi.nlm.nih.gov/books/NBK25501/) [](docs/ENDNOTE_EXPORT.md)

🧬 PubMed Data Server v2.0

🔬 极简架构，专注数据提供 - 为LLM提供结构化的PubMed文献数据

---

🎯 核心功能

> 四大核心功能，满足学术研究的全方位需求

📚 论文索引搜索 - 智能文献检索

• 关键词搜索：支持复杂查询语法，精准定位相关文献
• 批量查询：一次获取多篇论文的详细信息
• 交叉引用：发现相关研究，构建知识网络
• 事实核查：验证研究结论，提供证据支持

💾 智能缓存系统 - 高效数据管理

• 本地缓存：避免重复API调用，提升响应速度
• 缓存统计：实时监控缓存状态和存储使用情况
• 智能更新：自动检测数据变化，保持缓存新鲜度
• 存储优化：压缩存储，节省磁盘空间

📄 OA论文全文下载 - 开放获取文献获取

• 全文检测：自动识别可下载的开放获取论文
• 智能下载：模拟人类行为，避免被反爬虫机制拦截
• 批量处理：支持大量论文的批量下载和管理
• 格式支持：PDF格式，便于阅读和引用

📋 EndNote格式导出 - 文献管理集成

• RIS格式：兼容EndNote、Zotero等主流文献管理软件
• BibTeX格式：支持LaTeX写作和学术引用
• 自动导出：查询结果自动生成引用文件
• 批量处理：支持大量文献的批量导出

🌐 代理支持 - 网络环境适配

• 代理开关控制：通过 PROXY_ENABLED 环境变量控制代理功能
• HTTP/HTTPS代理：支持企业网络和防火墙环境
• 认证代理：支持用户名密码认证的代理服务器
• 自动检测：智能识别代理配置，无缝切换
• 故障恢复：代理失败时自动降级到直连模式
• 超时重试：可配置代理超时时间和重试次数

---

🎯 核心理念

MCP服务器 = 数据提供者，外部LLM = 智能分析

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

核心优势：

• ✅ 极简配置：只需PubMed API和邮箱
• ✅ LLM友好：结构化输出，优化上下文窗口
• ✅ 高效检索：批量查询、交叉引用、事实核查

---

🚀 快速部署

前置要求

安装Node.js (v18.0.0+)：nodejs.org

步骤一：下载项目

git clone [项目地址] mcp-pubmed-server
cd mcp-pubmed-server

步骤二：安装依赖

npm install

步骤三：配置API密钥

cp .env.example .env
# 编辑.env文件，填入以下内容：

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

获取API密钥：

1. 访问 NCBI API Key Management
2. 登录NCBI账户，生成API密钥

步骤四：测试服务器

node src/index.js
# 看到 "PubMed Data Server v2.0 running on stdio" 表示成功

> 环境变量说明：项目已内置 .env 自动加载（使用 dotenv）。在项目根目录创建 .env，例如：

PUBMED_API_KEY=你的NCBI_API密钥
PUBMED_EMAIL=你的邮箱地址
# 摘要截断模式：quick | deep
# quick：1500 字符（快速检索，可能不包含完整摘要）
# deep：6000 字符（深度检索；建议模型上下文窗口 ≥ 120k tokens）
ABSTRACT_MODE=quick
# 全文模式：disabled | enabled | auto
# disabled：禁用全文功能（默认）
# enabled：启用全文检测，手动下载
# auto：启用全文检测，自动下载可用的OA论文
FULLTEXT_MODE=disabled
# EndNote导出：enabled | disabled
# enabled：自动导出RIS和BibTeX格式（默认）
# disabled：禁用EndNote导出
ENDNOTE_EXPORT=enabled
# 代理配置（可选）
# 代理开关：enabled | disabled
PROXY_ENABLED=disabled
# HTTP代理：用于HTTP和HTTPS请求
HTTP_PROXY=http://proxy.example.com:8080
# HTTPS代理：专门用于HTTPS请求
HTTPS_PROXY=https://proxy.example.com:8080
# 支持认证代理：http://username:password@proxy.example.com:8080
# 代理认证（可选）
PROXY_USERNAME=
PROXY_PASSWORD=
# 代理超时设置（秒）
PROXY_TIMEOUT=30
# 代理重试次数
PROXY_RETRY_COUNT=3

步骤五：MCP客户端配置

1. Cline (VS Code Extension) 配置

{
  "mcpServers": {
    "pubmed-data-server": {
      "command": "node",
      "args": ["./src/index.js"],
      "cwd": "完整路径/to/mcp-pubmed-server",
      "env": {
        "PUBMED_API_KEY": "你的API密钥",
        "PUBMED_EMAIL": "你的邮箱地址",
        "ABSTRACT_MODE": "deep",
        "FULLTEXT_MODE": "enabled",
        "PROXY_ENABLED": "disabled",
        "HTTP_PROXY": "",
        "HTTPS_PROXY": ""
      }
    }
  }
}

路径示例：

• Linux/macOS: /home/user/mcp-pubmed-server
• Windows: C:/Users/YourUser/mcp-pubmed-server

2. Cherry Studio (Windows) 配置

{
  "mcpServers": {
    "VBFfGqCFz9AuZJXX2f5GL": {
      "name": "pubmed-data-server",
      "type": "stdio",
      "isActive": true,
      "command": "node",
      "args": [
        "Y:/software/mcp-pubmed-server/src/index.js"
      ],
      "env": {
        "PUBMED_API_KEY": "你的API密钥",
        "PUBMED_EMAIL": "你的邮箱地址",
        "ABSTRACT_MODE": "deep",
        "FULLTEXT_MODE": "enabled",
        "PROXY_ENABLED": "disabled",
        "HTTP_PROXY": "",
        "HTTPS_PROXY": ""
      }
    }
  }
}

Windows 网络映射配置说明：

• Y:/ - Samba 网络驱动器映射路径
• 也可以使用本地路径如 C:/mcp-pubmed-server/src/index.js
• 注意: Cherry Studio 不支持 cwd 参数

3. Claude Desktop 配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pubmed-data-server": {
      "command": "node",
      "args": ["/mnt/1T/software/mcp-pubmed-server/src/index.js"],
      "cwd": "/mnt/1T/software/mcp-pubmed-server",
      "env": {
        "PUBMED_API_KEY": "你的API密钥",
        "PUBMED_EMAIL": "你的邮箱地址",
        "ABSTRACT_MODE": "deep",
        "FULLTEXT_MODE": "enabled",
        "PROXY_ENABLED": "disabled",
        "HTTP_PROXY": "",
        "HTTPS_PROXY": ""
      }
    }
  }
}

或使用项目内置模板：

cp config/claude_desktop_config.json.example config/claude_desktop_config.json
# 编辑配置文件，填入API密钥

4. Claude Code (CLI) 配置

编辑 ~/.claude/config.json:

{
  "mcpServers": {
    "pubmed-data-server": {
      "command": "node",
      "args": ["/mnt/1T/software/mcp-pubmed-server/src/index.js"],
      "cwd": "/mnt/1T/software/mcp-pubmed-server",
      "env": {
        "PUBMED_API_KEY": "你的API密钥",
        "PUBMED_EMAIL": "你的邮箱地址",
        "ABSTRACT_MODE": "deep",
        "FULLTEXT_MODE": "enabled",
        "PROXY_ENABLED": "disabled",
        "HTTP_PROXY": "",
        "HTTPS_PROXY": ""
      }
    }
  }
}

步骤六：验证集成

在客户端中测试：使用pubmed_search工具搜索"acupuncture"

---

🛠️ 11个高效工具

1. pubmed_search - 智能文献搜索

{
  "query": "acupuncture gut microbiome",
  "max_results": 20,
  "days_back": 30,
  "sort_by": "relevance"
}

2. pubmed_get_details - 详细信息获取

{
  "pmids": ["38412345", "38412346"],
  "include_full_text": true
}

3. pubmed_extract_key_info - 关键信息提取

{
  "pmid": "38412345",
  "extract_sections": ["basic_info", "abstract_summary", "authors", "keywords"],
  "max_abstract_length": 2000
}

4. pubmed_cross_reference - 交叉引用分析

{
  "pmid": "38412345",
  "reference_type": "similar",
  "max_results": 10
}

5. pubmed_batch_query - 批量查询优化

{
  "pmids": ["38412345", "38412346", "38412347"],
  "query_format": "llm_optimized",
  "include_abstracts": true
}

6. pubmed_detect_fulltext - 检测全文可用性

{
  "pmid": "38412345",
  "auto_download": false
}

7. pubmed_download_fulltext - 下载全文PDF

{
  "pmid": "38412345",
  "force_download": false
}

8. pubmed_fulltext_status - 全文缓存管理

{
  "action": "stats",
  "pmid": "38412345"
}

9. pubmed_batch_download - 批量智能下载

{
  "pmids": ["38412345", "38412346", "38412347"],
  "human_like": true
}

10. pubmed_system_check - 系统环境检测

{}

11. pubmed_endnote_status - EndNote导出管理

{
  "action": "stats"
}

---

🏗️ 架构特色

📊 LLM优化输出

• 简洁格式：标题、作者、期刊、日期
• 详细格式：完整元数据+结构化摘要
• LLM优化格式：智能截断、关键点提取、关键词组织

🧠 上下文窗口管理

• 摘要截断模式（通过环境变量配置）：
• QUICK 模式：1500 字符，快速检索，可能不包含完整摘要
• DEEP 模式：6000 字符，深度检索；建议模型上下文窗口 ≥ 120k tokens（批量查询时更稳妥）
• 关键点提取（5个要点）
• 结构化信息分层

🔍 事实核查支持

• 交叉引用相关文献
• 相似研究对比
• 综述文献查找

⚡ 性能优化

• 速率限制管理（PubMed API限制）
• 批量查询优化（最多20个PMID）
• 错误重试机制

---

📝 使用场景

🔬 学术研究辅助

用户：我想了解针灸治疗肠易激综合征的最新研究
LLM → pubmed_search → 获取数据 → 智能分析和总结

✅ 事实核查

用户：这篇论文说某种化合物能治疗癌症，是真的吗？
LLM → pubmed_get_details → pubmed_cross_reference → 核查相关研究

📈 文献综述

用户：帮我分析某个领域的研究趋势
LLM → 批量查询 → 趋势分析 → 研究方向建议

💡 生物学问答

用户：某个蛋白质的功能是什么？
LLM → pubmed_search → pubmed_extract_key_info → 精准回答

---

📁 项目结构

mcp-pubmed-server/
├── src/
│   └── index.js              # 主服务器代码
├── config/
│   ├── mcp-config.json       # MCP配置模板
│   └── claude_desktop_config.json  # Claude Desktop配置
├── .env.example              # 环境变量模板
├── package.json              # 项目依赖配置
└── README.md                 # 本文件

---

🔍 故障排除

常见问题

1. "找不到模块 @modelcontextprotocol/sdk"

``bash npm install ``

1. "PubMed API调用失败"

• 检查API密钥是否正确
• 确认网络连接正常
• 等待速率限制重置

1. "环境变量未设置"

• 确保 .env 文件存在
• 检查变量名拼写

1. Cherry Studio配置错误

• 使用完整路径到 src/index.js
• 不要使用 cwd 参数
• 使用正斜杠 / 或双反斜杠 \\

1. 代理连接问题

• 检查 PROXY_ENABLED 是否设置为 enabled
• 检查代理服务器地址和端口是否正确
• 确认代理服务器支持HTTPS连接
• 验证代理认证信息（如需要）
• 格式：http://username:password@proxy.example.com:8080
• 检查代理超时设置是否合理（默认30秒）
• 确认代理重试次数设置（默认3次）

部署清单

• [ ] Node.js已安装
• [ ] 依赖已安装 (npm install)
• [ ] .env 文件已配置
• [ ] 服务器可正常启动
• [ ] MCP客户端配置正确

---

📄 许可证

Apache License 2.0

---

📚 详细文档

• [全文模式与智能下载系统完整指南](docs/FULLTEXTSMARTDOWNLOAD.md) - 完整的全文模式和跨平台智能下载使用指南
• [EndNote导出功能使用指南](docs/ENDNOTE_EXPORT.md) - EndNote兼容格式自动导出功能
• [配置说明文档](docs/CONFIGURATION.md) - 环境变量和MCP客户端配置指南
• [项目结构说明](.cursor/rules/README.md) - Cursor规则和项目架构说明

🧪 测试工具

代理功能测试

# 测试代理配置和连接
node test-proxy.js

该脚本会：

• 检查代理环境变量配置
• 测试代理连接是否正常
• 验证PubMed API是否可通过代理访问
• 提供详细的配置指导

---

🎉 简单、高效、专注 - 现代MCP服务标准

版本 2.0 - 简化架构，专注数据提供

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hhx465453939
• Source: hhx465453939/mcp-pubmed-server
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.