# Mcp Pubmed Server

> 一个用来让本地agent利用api高效爬取pubmed论文的mcp工具

- **Type:** MCP server
- **Install:** `agentstack add mcp-hhx465453939-mcp-pubmed-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hhx465453939](https://agentstack.voostack.com/s/hhx465453939)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [hhx465453939](https://github.com/hhx465453939)
- **Source:** https://github.com/hhx465453939/mcp-pubmed-server

## Install

```sh
agentstack add mcp-hhx465453939-mcp-pubmed-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

[](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](https://nodejs.org/)

### 步骤一：下载项目
```bash
git clone [项目地址] mcp-pubmed-server
cd mcp-pubmed-server
```

### 步骤二：安装依赖
```bash
npm install
```

### 步骤三：配置API密钥
```bash
cp .env.example .env
# 编辑.env文件，填入以下内容：
```

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

**获取API密钥：**
1. 访问 [NCBI API Key Management](https://www.ncbi.nlm.nih.gov/account/settings/)
2. 登录NCBI账户，生成API密钥

### 步骤四：测试服务器
```bash
node src/index.js
# 看到 "PubMed Data Server v2.0 running on stdio" 表示成功
```

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

```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) 配置
```json
{
  "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) 配置
```json
{
  "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):

```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": ""
      }
    }
  }
}
```

**或使用项目内置模板：**
```bash
cp config/claude_desktop_config.json.example config/claude_desktop_config.json
# 编辑配置文件，填入API密钥
```

#### 4. Claude Code (CLI) 配置
编辑 `~/.claude/config.json`:

```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` - 智能文献搜索
```json
{
  "query": "acupuncture gut microbiome",
  "max_results": 20,
  "days_back": 30,
  "sort_by": "relevance"
}
```

### 2. `pubmed_get_details` - 详细信息获取
```json
{
  "pmids": ["38412345", "38412346"],
  "include_full_text": true
}
```

### 3. `pubmed_extract_key_info` - 关键信息提取
```json
{
  "pmid": "38412345",
  "extract_sections": ["basic_info", "abstract_summary", "authors", "keywords"],
  "max_abstract_length": 2000
}
```

### 4. `pubmed_cross_reference` - 交叉引用分析
```json
{
  "pmid": "38412345",
  "reference_type": "similar",
  "max_results": 10
}
```

### 5. `pubmed_batch_query` - 批量查询优化
```json
{
  "pmids": ["38412345", "38412346", "38412347"],
  "query_format": "llm_optimized",
  "include_abstracts": true
}
```

### 6. `pubmed_detect_fulltext` - 检测全文可用性
```json
{
  "pmid": "38412345",
  "auto_download": false
}
```

### 7. `pubmed_download_fulltext` - 下载全文PDF
```json
{
  "pmid": "38412345",
  "force_download": false
}
```

### 8. `pubmed_fulltext_status` - 全文缓存管理
```json
{
  "action": "stats",
  "pmid": "38412345"
}
```

### 9. `pubmed_batch_download` - 批量智能下载
```json
{
  "pmids": ["38412345", "38412346", "38412347"],
  "human_like": true
}
```

### 10. `pubmed_system_check` - 系统环境检测
```json
{}
```

### 11. `pubmed_endnote_status` - EndNote导出管理
```json
{
  "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
   ```

2. **"PubMed API调用失败"**
   - 检查API密钥是否正确
   - 确认网络连接正常
   - 等待速率限制重置

3. **"环境变量未设置"**
   - 确保 `.env` 文件存在
   - 检查变量名拼写

4. **Cherry Studio配置错误**
   - 使用完整路径到 `src/index.js`
   - 不要使用 `cwd` 参数
   - 使用正斜杠 `/` 或双反斜杠 `\\`

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

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

---

## 📄 许可证

Apache License 2.0

---

## 📚 详细文档

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

## 🧪 测试工具

### 代理功能测试
```bash
# 测试代理配置和连接
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](https://github.com/hhx465453939)
- **Source:** [hhx465453939/mcp-pubmed-server](https://github.com/hhx465453939/mcp-pubmed-server)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-hhx465453939-mcp-pubmed-server
- Seller: https://agentstack.voostack.com/s/hhx465453939
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.