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 速率限制和服務條款。