pubmed-search-mcp 0.2.2

MCP server for PubMed literature search with MeSH, PICO, and intelligent query expansion

PubMed Search MCP

Professional Literature Research Assistant for AI Agents - More than just an API wrapper

A Domain-Driven Design (DDD) based MCP server that serves as an intelligent research assistant for AI agents, providing task-oriented literature search and analysis capabilities.

✨ What's Included:

• 🔧 21 MCP Tools - Streamlined PubMed, Europe PMC, CORE, and NCBI database access
• 📚 22 Claude Skills - Ready-to-use workflow guides for AI agents (Claude Code-specific)
• 📖 Copilot Instructions - VS Code GitHub Copilot integration guide

🌐 Language: English | 繁體中文

---

🚀 Quick Install

Via uv

uv add pubmed-search-mcp

Via uvx (Zero Install)

uvx pubmed-search-mcp

---

⚙️ Configuration

This MCP server works with any MCP-compatible AI tool. Choose your preferred client:

VS Code / Cursor (.vscode/mcp.json)

{
  "servers": {
    "pubmed-search": {
      "type": "stdio",
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "[e-mail]"
      }
    }
  }
}

Cline (cline_mcp_settings.json)

{
  "mcpServers": {
    "pubmed-search": {
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "[e-mail]"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

Tip: In Cline, click "MCP Servers" → "Configure" → "Configure MCP Servers" to edit this file.

Antigravity / Other MCP Clients

Any MCP-compatible client can use this server via stdio transport:

# Command
uvx pubmed-search-mcp

Note: NCBI_EMAIL is required by NCBI API policy. Optionally set NCBI_API_KEY for higher rate limits.

---

🎯 Design Philosophy

Core Positioning: The intelligent middleware between AI Agents and academic search engines.

Why This Server?

Other tools give you raw API access. We give you vocabulary translation + intelligent routing:

Challenge	Our Solution
Agent uses ICD codes, PubMed needs MeSH	✅ Auto ICD→MeSH conversion
Multiple databases, different APIs	✅ Unified Search single entry point
Clinical questions need structured search	✅ PICO parser with Boolean builder
Typos in medical terms	✅ ESpell auto-correction
Too many results from one source	✅ Parallel multi-source with dedup

Key Differentiators

1. Vocabulary Translation Layer - Agent speaks naturally, we translate to each database's terminology (MeSH, ICD-10, text-mined entities)
2. Unified Search Gateway - One unified_search() call, auto-dispatch to PubMed/Europe PMC/CORE/OpenAlex
3. PICO-Aware - Parse clinical questions into structured (P)opulation/(I)ntervention/(C)omparison/(O)utcome
4. Agent-First Design - Output optimized for machine decision-making, not human reading

---

📡 External APIs & Data Sources

This MCP server integrates with multiple academic databases and APIs:

Core Data Sources

Source	Coverage	Vocabulary	Auto-Convert	Description
NCBI PubMed	36M+ articles	MeSH	✅ Native	Primary biomedical literature
NCBI Entrez	Multi-DB	MeSH	✅ Native	Gene, PubChem, ClinVar
Europe PMC	33M+	Text-mined	✅ Extraction	Full text XML access
CORE	200M+	None	➡️ Free-text	Open access aggregator
Semantic Scholar	200M+	S2 Fields	➡️ Free-text	AI-powered recommendations
OpenAlex	250M+	Concepts	➡️ Free-text	Open scholarly metadata
NIH iCite	PubMed	N/A	N/A	Citation metrics (RCR)

🔑 Key: ✅ = Full vocabulary support | ➡️ = Query pass-through (no controlled vocabulary)

ICD Codes: Auto-detected and converted to MeSH before PubMed search

Environment Variables

# Required
NCBI_EMAIL=[e-mail]          # Required by NCBI policy

# Optional - For higher rate limits
NCBI_API_KEY=your_ncbi_api_key     # Get from: https://www.ncbi.nlm.nih.gov/account/settings/
CORE_API_KEY=your_core_api_key     # Get from: https://core.ac.uk/services/api
S2_API_KEY=your_s2_api_key         # Get from: https://www.semanticscholar.org/product/api

# Optional - Network settings
HTTP_PROXY=http://proxy:8080       # HTTP proxy for API requests
HTTPS_PROXY=https://proxy:8080     # HTTPS proxy for API requests

🔄 How It Works: The Middleware Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              AI AGENT                                        │
│                                                                              │
│   "Find papers about I10 hypertension treatment in diabetic patients"       │
│                                                                              │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                     🔄 PUBMED SEARCH MCP (MIDDLEWARE)                        │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │  1️⃣ VOCABULARY TRANSLATION                                              ││
│  │     • ICD-10 "I10" → MeSH "Hypertension"                                ││
│  │     • "diabetic" → MeSH "Diabetes Mellitus"                             ││
│  │     • ESpell: "hypertention" → "hypertension"                           ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │  2️⃣ INTELLIGENT ROUTING                                                 ││
│  │     ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐             ││
│  │     │ PubMed   │  │Europe PMC│  │   CORE   │  │ OpenAlex │             ││
│  │     │  36M+    │  │   33M+   │  │  200M+   │  │  250M+   │             ││
│  │     │  (MeSH)  │  │(fulltext)│  │  (OA)    │  │(metadata)│             ││
│  │     └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘             ││
│  │          └──────────────┴──────────────┴──────────────┘                 ││
│  │                              ▼                                          ││
│  │  3️⃣ RESULT AGGREGATION: Dedupe + Rank + Enrich                         ││
│  └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         UNIFIED RESULTS                                      │
│   • 150 unique papers (deduplicated from 4 sources)                          │
│   • Ranked by relevance + citation impact (RCR)                              │
│   • Full text links enriched from Europe PMC                                 │
└─────────────────────────────────────────────────────────────────────────────┘

---

🛠️ MCP Tools Overview

🔍 Search Tools

┌─────────────────────────────────────────────────────────────────┐
│                      SEARCH ENTRY POINTS                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   unified_search()          ← 🌟 RECOMMENDED: Auto-routing       │
│        │                                                         │
│        ├── Quick search     → Direct multi-source query          │
│        ├── PICO mode        → Clinical question decomposition    │
│        └── Systematic mode  → MeSH expansion + parallel search   │
│                                                                  │
├─────────────────────────────────────────────────────────────────┤
│   SPECIALIZED SEARCH (when you need specific source)            │
│                                                                  │
│   search_literature()       → PubMed only (MeSH support)         │
│   search_europe_pmc()       → Europe PMC (fulltext/OA filters)   │
│   search_core()             → CORE 200M+ open access             │
│   search_gene()             → NCBI Gene database                 │
│   search_compound()         → PubChem compounds                  │
│   search_clinvar()          → ClinVar variants                   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

🔬 Discovery Tools (After Finding Key Papers)

                        Found important paper (PMID)
                                   │
           ┌───────────────────────┼───────────────────────┐
           │                       │                       │
           ▼                       ▼                       ▼
    ┌─────────────┐        ┌─────────────┐        ┌─────────────┐
    │  BACKWARD   │        │  SIMILAR    │        │  FORWARD    │
    │  ◀──────    │        │  ≈≈≈≈≈≈     │        │  ──────▶    │
    │             │        │             │        │             │
    │ get_article │        │find_related │        │find_citing  │
    │ _references │        │ _articles   │        │ _articles   │
    │             │        │             │        │             │
    │ Foundation  │        │  Similar    │        │ Follow-up   │
    │  papers     │        │   topic     │        │  research   │
    └─────────────┘        └─────────────┘        └─────────────┘

    build_citation_tree() → Full network visualization (6 formats)

📚 Full Text & Export

Category	Tools
Full Text	get_fulltext (Europe PMC), get_core_fulltext (CORE), get_fulltext_xml
Text Mining	get_text_mined_terms → Extract genes, diseases, chemicals
Export	prepare_export → RIS/BibTeX/CSV/MEDLINE/JSON
Metrics	get_citation_metrics → iCite RCR, citation percentile

---

📋 Agent Usage Examples

1️⃣ Quick Search (Simplest)

# Agent just asks naturally - middleware handles everything
unified_search(query="remimazolam ICU sedation", limit=20)

# Or with clinical codes - auto-converted to MeSH
unified_search(query="I10 treatment in E11.9 patients")
#                     ↑ ICD-10           ↑ ICD-10
#                     Hypertension       Type 2 Diabetes

2️⃣ PICO Clinical Question

┌─────────────────────────────────────────────────────────────────────────┐
│  "Is remimazolam better than propofol for ICU sedation?"                │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         parse_pico()                                     │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐                     │
│  │    P    │  │    I    │  │    C    │  │    O    │                     │
│  │  ICU    │  │remimaz- │  │propofol │  │sedation │                     │
│  │patients │  │  olam   │  │         │  │outcomes │                     │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘                     │
└───────┼────────────┼────────────┼────────────┼──────────────────────────┘
        │            │            │            │
        ▼            ▼            ▼            ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              generate_search_queries() × 4 (parallel)                    │
│                                                                          │
│  P → "Intensive Care Units"[MeSH]                                        │
│  I → "remimazolam" [Supplementary Concept], "CNS 7056"                   │
│  C → "Propofol"[MeSH], "Diprivan"                                        │
│  O → "Conscious Sedation"[MeSH], "Deep Sedation"[MeSH]                   │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              Agent combines with Boolean logic                           │
│                                                                          │
│  (P) AND (I) AND (C) AND (O)  ← High precision                           │
│  (P) AND (I OR C) AND (O)     ← High recall                              │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              unified_search() × N (parallel multi-source)                │
│                                                                          │
│  PubMed ──┬── Europe PMC ──┬── CORE ──► merge_search_results()           │
└─────────────────────────────────────────────────────────────────────────┘

# Step 1: Parse clinical question
parse_pico("Is remimazolam better than propofol for ICU sedation?")
# Returns: P=ICU patients, I=remimazolam, C=propofol, O=sedation outcomes

# Step 2: Get MeSH for each element (parallel!)
generate_search_queries(topic="ICU patients")   # P
generate_search_queries(topic="remimazolam")    # I
generate_search_queries(topic="propofol")       # C
generate_search_queries(topic="sedation")       # O

# Step 3: Agent combines with Boolean
query = '("Intensive Care Units"[MeSH]) AND (remimazolam OR "CNS 7056") AND propofol AND sedation'

# Step 4: Search and merge
unified_search(query=query, sources=["pubmed", "europe_pmc", "core"])

3️⃣ Explore from Key Paper

# Found landmark paper PMID: 33475315
find_related_articles(pmid="33475315")   # Similar methodology
find_citing_articles(pmid="33475315")    # Who built on this?
get_article_references(pmid="33475315")  # What's the foundation?

# Build complete research map
build_citation_tree(pmid="33475315", depth=2, output_format="mermaid")

4️⃣ Gene/Drug Research

# Research a gene
search_gene(query="BRCA1", organism="human")
get_gene_literature(gene_id="672", limit=20)

# Research a drug compound
search_compound(query="propofol")
get_compound_literature(cid="4943", limit=20)

5️⃣ Export Results

# Export last search results
prepare_export(pmids="last", format="ris")      # → EndNote/Zotero
prepare_export(pmids="last", format="bibtex")   # → LaTeX

# Check open access availability
analyze_fulltext_access(pmids="last")

---

🔍 Search Mode Comparison

┌─────────────────────────────────────────────────────────────────────────┐
│                        SEARCH MODE DECISION TREE                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   "What kind of search do I need?"                                       │
│         │                                                                │
│         ├── Know exactly what to search?                                 │
│         │   └── unified_search(query="topic keywords")                   │
│         │       → Quick, auto-routing to best sources                    │
│         │                                                                │
│         ├── Have a clinical question (A vs B)?                           │
│         │   └── parse_pico() → unified_search(mode="pico")               │
│         │       → Structured P/I/C/O search with Boolean                 │
│         │                                                                │
│         ├── Need comprehensive systematic coverage?                      │
│         │   └── generate_search_queries() → parallel search              │
│         │       → MeSH expansion, multiple strategies, merge             │
│         │                                                                │
│         └── Exploring from a key paper?                                  │
│             └── find_related/citing/references → build_citation_tree     │
│                 → Citation network, research context                     │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Mode	Entry Point	Best For	Auto-Features
Quick	unified_search()	Fast topic search	ICD→MeSH, multi-source, dedup
PICO	parse_pico()	Clinical questions	P/I/C/O decomposition, Boolean
Systematic	generate_search_queries()	Literature reviews	MeSH expansion, synonyms
Exploration	find_*_articles()	From key paper	Citation network, related

---

🤖 Claude Skills (AI Agent Workflows)

Pre-built workflow guides in .claude/skills/:

Skill	Description
pubmed-quick-search	Basic search with filters
pubmed-systematic-search	MeSH expansion, comprehensive
pubmed-pico-search	Clinical question decomposition
pubmed-paper-exploration	Citation tree, related articles
pubmed-gene-drug-research	Gene/PubChem/ClinVar
pubmed-fulltext-access	Europe PMC, CORE full text
pubmed-export-citations	RIS/BibTeX/CSV export

📁 Location: .claude/skills/*/SKILL.md (Claude Code-specific)

---

🏗️ Architecture (DDD)

This project uses Domain-Driven Design (DDD) architecture, with literature research domain knowledge as the core model.

src/pubmed_search/
├── domain/                     # Core business logic
│   └── entities/article.py     # UnifiedArticle, Author, etc.
├── application/                # Use cases
│   ├── search/                 # QueryAnalyzer, ResultAggregator
│   ├── export/                 # Citation export (RIS, BibTeX...)
│   └── session/                # SessionManager
├── infrastructure/             # External systems
│   ├── ncbi/                   # Entrez, iCite, Citation Exporter
│   ├── sources/                # Europe PMC, CORE, CrossRef...
│   └── http/                   # HTTP clients
├── presentation/               # User interfaces
│   ├── mcp_server/             # MCP tools, prompts, resources
│   │   └── tools/              # discovery, strategy, pico, export...
│   └── api/                    # REST API (Copilot Studio)
└── shared/                     # Cross-cutting concerns
    ├── exceptions.py           # Unified error handling
    └── async_utils.py          # Rate limiter, retry, circuit breaker

Internal Mechanisms (Transparent to Agent)

Mechanism	Description
Session	Auto-create, auto-switch
Cache	Auto-cache search results, avoid duplicate API calls
Rate Limit	Auto-comply with NCBI API limits (0.34s/0.1s)
MeSH Lookup	generate_search_queries() auto-queries NCBI MeSH database
ESpell	Auto spelling correction (remifentanyl → remifentanil)
Query Analysis	Each suggested query shows how PubMed actually interprets it

Vocabulary Translation Layer (Key Feature)

Our Core Value: We are the intelligent middleware between Agent and Search Engines, automatically handling vocabulary standardization so Agent doesn't need to know each database's terminology.

Different data sources use different controlled vocabulary systems. This server provides automatic conversion:

API / Database	Vocabulary System	Auto-Conversion
PubMed / NCBI	MeSH (Medical Subject Headings)	✅ Full support via expand_with_mesh()
ICD Codes	ICD-10-CM / ICD-9-CM	✅ Auto-detect & convert to MeSH
Europe PMC	Text-mined entities (Gene, Disease, Chemical)	✅ get_text_mined_terms() extraction
OpenAlex	OpenAlex Concepts (deprecated)	❌ Free-text only
Semantic Scholar	S2 Field of Study	❌ Free-text only
CORE	None	❌ Free-text only
CrossRef	None	❌ Free-text only

Automatic ICD → MeSH Conversion

When searching with ICD codes (e.g., I10 for Hypertension), unified_search() automatically:

1. Detects ICD-10/ICD-9 patterns via detect_and_expand_icd_codes()
2. Looks up corresponding MeSH terms from internal mapping (ICD10_TO_MESH, ICD9_TO_MESH)
3. Expands query with MeSH synonyms for comprehensive search

# Agent calls unified_search with clinical terminology
unified_search(query="I10 treatment outcomes")

# Server auto-expands to PubMed-compatible query
"(I10 OR Hypertension[MeSH]) treatment outcomes"

📖 Full architecture documentation: ARCHITECTURE.md

MeSH Auto-Expansion + Query Analysis

When calling generate_search_queries("remimazolam sedation"), internally it:

1. ESpell Correction - Fix spelling errors
2. MeSH Query - Entrez.esearch(db="mesh") to get standard vocabulary
3. Synonym Extraction - Get synonyms from MeSH Entry Terms
4. Query Analysis - Analyze how PubMed interprets each query

{
  "mesh_terms": [
    {
      "input": "remimazolam",
      "preferred": "remimazolam [Supplementary Concept]",
      "synonyms": ["CNS 7056", "ONO 2745"]
    }
  ],
  "all_synonyms": ["CNS 7056", "ONO 2745", ...],
  "suggested_queries": [
    {
      "id": "q1_title",
      "query": "(remimazolam sedation)[Title]",
      "purpose": "Exact title match - highest precision",
      "estimated_count": 8,
      "pubmed_translation": "\"remimazolam sedation\"[Title]"
    },
    {
      "id": "q3_and",
      "query": "(remimazolam AND sedation)",
      "purpose": "All keywords required",
      "estimated_count": 561,
      "pubmed_translation": "(\"remimazolam\"[Supplementary Concept] OR \"remimazolam\"[All Fields]) AND (\"sedate\"[All Fields] OR ...)"
    }
  ]
}

Value of Query Analysis: Agent thinks remimazolam AND sedation only searches these two words, but PubMed actually expands to Supplementary Concept + synonyms, results go from 8 to 561. This helps Agent understand the difference between intent and actual search.

---

🔒 HTTPS Deployment

Enable HTTPS secure communication for production environments.

Quick Start

# Step 1: Generate SSL certificates
./scripts/generate-ssl-certs.sh

# Step 2: Start HTTPS service (Docker)
./scripts/start-https-docker.sh up

# Verify deployment
curl -k https://localhost/

HTTPS Endpoints

Service	URL	Description
MCP SSE	https://localhost/sse	SSE connection (MCP)
Messages	https://localhost/messages	MCP POST
Health	https://localhost/health	Health check

Claude Desktop Configuration

{
  "mcpServers": {
    "pubmed-search": {
      "url": "https://localhost/sse"
    }
  }
}

---

🏢 Microsoft Copilot Studio Integration

Integrate PubMed Search MCP with Microsoft 365 Copilot (Word, Teams, Outlook)!

Quick Start

# Start with Streamable HTTP transport (required by Copilot Studio)
python run_server.py --transport streamable-http --port 8765

# Or use the dedicated script with ngrok
./scripts/start-copilot-studio.sh --with-ngrok

Copilot Studio Configuration

Field	Value
Server name	PubMed Search
Server URL	https://your-server.com/mcp
Authentication	None (or API Key)

📖 Full documentation: copilot-studio/README.md

⚠️ Note: SSE transport deprecated since Aug 2025. Use streamable-http.

---

📖 More documentation:

• Architecture → ARCHITECTURE.md
• Deployment guide → DEPLOYMENT.md
• Copilot Studio → copilot-studio/README.md

---

🔐 Security

Security Features

Layer	Feature	Description
HTTPS	TLS 1.2/1.3 encryption	All traffic encrypted via Nginx
Rate Limiting	30 req/s	Nginx level protection
Security Headers	XSS/CSRF protection	X-Frame-Options, X-Content-Type-Options
SSE Optimization	24h timeout	Long-lived connections for real-time
No Database	Stateless	No SQL injection risk
No Secrets	In-memory only	No credentials stored

See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed deployment instructions.

---

## 📤 Export Formats

Export your search results in formats compatible with major reference managers:

| Format | Compatible With | Use Case |
|--------|-----------------|----------|
| **RIS** | EndNote, Zotero, Mendeley | Universal import |
| **BibTeX** | LaTeX, Overleaf, JabRef | Academic writing |
| **CSV** | Excel, Google Sheets | Data analysis |
| **MEDLINE** | PubMed native format | Archiving |
| **JSON** | Programmatic access | Custom processing |

### Exported Fields
- **Core**: PMID, Title, Authors, Journal, Year, Volume, Issue, Pages
- **Identifiers**: DOI, PMC ID, ISSN
- **Content**: Abstract (HTML tags cleaned)
- **Metadata**: Language, Publication Type, Keywords
- **Access**: DOI URL, PMC URL, Full-text availability

### Special Character Handling
- BibTeX exports use **pylatexenc** for proper LaTeX encoding
- Nordic characters (ø, æ, å), umlauts (ü, ö, ä), and accents are correctly converted
- Example: `Søren Hansen` → `S{\o}ren Hansen`



---

## 📄 License

Apache License 2.0 - see [LICENSE](LICENSE)

---

## �🔗 Links

- [GitHub Repository](https://github.com/u9401066/pubmed-search-mcp)
- [PyPI Package](https://pypi.org/project/pubmed-search/)
- [NCBI Entrez Programming Utilities](https://www.ncbi.nlm.nih.gov/books/NBK25497/)