Pubmed MCP

🚀 PubMed MCP Server

PubMed MCP Server 是一个全面的模型上下文协议（MCP）服务器，用于 PubMed 文献搜索和管理。它通过 MCP 协议提供了高级搜索功能、引用格式设置以及研究分析工具，能极大提升文献搜索与管理的效率。

🚀 快速开始

前提条件

• Python 3.8 或更高版本
• NCBI API 密钥（需免费注册）
• 用于 NCBI API 识别的有效电子邮件地址

快速启动步骤

1. 克隆仓库：

git clone https://github.com/your-org/pubmed-mcp.git
cd pubmed-mcp

2. 安装依赖：

pip install -r requirements.txt

3. 设置环境变量：

cp env.example .env
# 使用你的 NCBI API 密钥和电子邮件编辑 .env 文件

4. 运行服务器：

python -m src.main

开发环境安装

若要使用额外工具进行开发，可以执行以下操作：

make install-dev

或者手动安装：

pip install -r requirements.txt
pip install -e .
pip install black isort mypy flake8

✨ 主要特性

• 高级 PubMed 搜索：支持使用复杂过滤器进行搜索，包括日期范围、文章类型、作者、期刊和医学主题词（MeSH）等。
• 文章详情获取：可检索特定 PMID 文章的详细信息，如摘要、作者和元数据。
• 引用导出：支持以多种格式（BibTeX、APA、MLA、芝加哥、温哥华、EndNote、RIS）导出文章引用。
• 作者搜索：根据特定作者搜索文章，并显示共同作者信息。
• 相关文章发现：查找与特定 PMID 文章相关的其他文章。
• MeSH 术语搜索：搜索和探索医学主题词。
• 期刊分析：获取特定期刊的指标和近期文章。
• 研究趋势分析：分析随时间变化的文章发表趋势。
• 文章对比：并排比较多篇文章。
• 缓存机制：内置缓存功能，提升性能。
• 速率限制：可配置 API 使用速率限制，确保合理使用 API。

📦 安装指南

配置文件设置

在项目根目录下创建一个 .env 文件，并设置以下变量：

# 必需
PUBMED_API_KEY=your_ncbi_api_key_here
PUBMED_EMAIL=your.email@example.com

# 可选
CACHE_TTL=300
CACHE_MAX_SIZE=1000
RATE_LIMIT=3.0
LOG_LEVEL=info

获取 NCBI API 密钥

1. 访问 NCBI 账户设置。
2. 登录或创建账户。
3. 导航到“API 密钥管理”。
4. 创建一个新的 API 密钥。
5. 将密钥复制到 .env 文件中。

💻 使用示例

可用工具

服务器提供了以下 MCP 工具：

1. search_pubmed

使用高级过滤选项搜索 PubMed。

{
  "query": "machine learning healthcare",
  "max_results": 20,
  "date_range": "5y",
  "article_types": ["Journal Article", "Review"],
  "has_abstract": true
}

2. get_article_details

获取特定 PMID 文章的详细信息。

{
  "pmids": ["12345678", "87654321"],
  "include_abstracts": true,
  "include_citations": false
}

3. search_by_author

根据特定作者搜索文章。

{
  "author_name": "Smith J",
  "max_results": 10,
  "include_coauthors": true
}

4. export_citations

以各种格式导出文章引用。

{
  "pmids": ["12345678"],
  "format": "bibtex",
  "include_abstracts": false
}

5. find_related_articles

查找与特定 PMID 文章相关的其他文章。

{
  "pmid": "12345678",
  "max_results": 10
}

6. search_mesh_terms

使用 MeSH 术语进行搜索。

{
  "term": "Machine Learning",
  "max_results": 20
}

7. analyze_research_trends

分析随时间变化的文章发表趋势。

{
  "topic": "artificial intelligence",
  "years_back": 5,
  "include_subtopics": false
}

使用 MCP 客户端的示例

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="python",
        args=["-m", "src.main"]
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # 初始化会话
            await session.initialize()

            # 搜索 PubMed
            result = await session.call_tool(
                "search_pubmed",
                {
                    "query": "COVID-19 vaccines",
                    "max_results": 5,
                    "date_range": "1y"
                }
            )

            print(result.content[0].text)

if __name__ == "__main__":
    asyncio.run(main())

🔧 技术细节

运行测试

# 运行所有测试
make test

# 运行带覆盖率的测试
make test-coverage

# 运行特定类型的测试
python run_tests.py unit
python run_tests.py integration
python run_tests.py coverage

代码质量检查

# 格式化代码
make format

# 运行代码检查
make lint

# 类型检查
mypy src/

项目结构

pubmed-mcp/
├── src/
│   ├── __init__.py
│   ├── main.py              # 入口点
│   ├── server.py            # MCP 服务器实现
│   ├── models.py            # Pydantic 模型
│   ├── pubmed_client.py     # PubMed API 客户端
│   ├── tool_handler.py      # 工具请求处理程序
│   ├── citation_formatter.py # 引用格式设置
│   ├── tools.py             # 工具定义
│   └── utils.py             # 实用函数
├── tests/                   # 测试套件
├── requirements.txt         # 依赖项
├── setup.py                 # 包设置
├── pyproject.toml          # 现代 Python 配置
├── Makefile                # 开发命令
├── Dockerfile              # 容器设置
└── README.md               # 本文件

Docker 使用

构建和运行

# 构建 Docker 镜像
make docker-build

# 使用环境变量运行
make docker-run PUBMED_API_KEY=your_key PUBMED_EMAIL=your_email

Docker Compose

version: '3.8'
services:
  pubmed-mcp:
    build: .
    environment:
      - PUBMED_API_KEY=your_key
      - PUBMED_EMAIL=your_email
      - LOG_LEVEL=info
    volumes:
      - ./data:/app/data

📚 详细文档

搜索参数

• query：使用 PubMed 语法的搜索查询。
• max_results：最大结果数量（1 - 200）。
• sort_order：排序顺序（相关性、出版日期、作者、期刊、标题）。
• date_from/date_to：日期范围过滤器。
• date_range：预定义的日期范围（1 年、5 年、10 年、所有）。
• article_types：按文章类型过滤。
• authors：按作者姓名过滤。
• journals：按期刊名称过滤。
• mesh_terms：按 MeSH 术语过滤。
• language：语言过滤器（如 'eng'、'fre'）。
• has_abstract：仅显示有摘要的文章。
• has_full_text：仅显示有全文的文章。
• humans_only：仅显示以人为研究对象的文章。

引用格式

• bibtex：BibTeX 格式。
• apa：APA 风格。
• mla：MLA 风格。
• chicago：芝加哥风格。
• vancouver：温哥华风格。
• endnote：EndNote 格式。
• ris：RIS 格式。

🤝 贡献指南

1. 分叉仓库。
2. 创建功能分支。
3. 进行更改。
4. 为新功能添加测试。
5. 运行测试套件。
6. 提交拉取请求。

开发准则

• 遵循 PEP 8 风格指南。
• 为所有函数添加类型提示。
• 编写全面的测试。
• 为新功能更新文档。
• 使用常规提交消息。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🛠️ 支持与反馈

• 问题反馈：GitHub Issues
• 文档查阅：项目维基
• 讨论交流：GitHub Discussions

🙏 致谢

• NCBI E-utilities 提供 PubMed API 访问。
• Model Context Protocol 提供 MCP 规范。
• Anthropic 提供 MCP 开发和支持。

📜 更新日志

详细的更改历史请参阅 CHANGELOG.md。

⚠️ 重要提示

此服务器需要有效的 NCBI API 密钥，并遵循 NCBI 的使用指南。请遵守 API 速率限制和服务条款。