PubMed MCP Server

🔍 Enable AI assistants to search, access, and analyze PubMed articles through a simple MCP interface.

The PubMed MCP Server provides a bridge between AI assistants and PubMed's vast repository of biomedical literature through the Model Context Protocol (MCP). It allows AI models to search for scientific articles, access their metadata, and perform deep analysis in a programmatic way.

🤝 Contribute • 📝 Report Bug

🔄 Europe PMC backend (v0.0.1)

This fork ships an additional pubmed_mcp_server package whose search backend is the Europe PMC REST API (https://www.ebi.ac.uk/europepmc/webservices/rest/search) instead of NCBI E-utilities.

Why Europe PMC replaces NCBI

When the server runs inside a sandbox / cloud environment (e.g. the ROCK sandbox), NCBI E-utilities frequently rate-limits or blocks the shared egress IP and returns an HTML error page. The upstream code feeds that HTML into an XML parser, so the tool call fails with:

Error executing tool search_pubmed_articles: mismatched tag: line 198, column 2

Europe PMC stays reachable from those environments, requires no API key, and covers PubMed content (source: MED) plus preprints, patents and Agricola records — so results are functionally equivalent to PubMed for most biomedical queries.

What changed

• Replaced the NCBI esearch + efetch XML flow with the Europe PMC REST API (format=json, resultType=core).
• Parses the Europe PMC JSON shape, including journalInfo.journal.title, authorList (with authorString fallback), pubYear/pubMonth/pubDay and abstractText.
• Keeps User-Agent / Accept headers, connect/read timeouts (10, 30) and retry with exponential backoff on 429/500/502/503.
• Preserves the original tool signature search_pubmed_articles(query, api_key=None) so existing demos keep working. api_key is accepted for compatibility but unused (Europe PMC needs none).

Local verification

# run the search layer directly
uv run --with requests python pubmed_mcp_server/pubmed.py

# or start the MCP server from a local checkout
uvx --from . --with "mcp<2" pubmed_mcp_server

✨ Core Features

• 🔎 Paper Search: Query PubMed articles with keywords or advanced search ✅
• 🚀 Efficient Retrieval: Fast access to paper metadata ✅
• 📊 Metadata Access: Retrieve detailed metadata for specific papers ✅
• 📊 Research Support: Facilitate biomedical sciences research and analysis ✅
• 📄 Paper Access: Attempt to download full-text PDF content ✅
• 🧠 Deep Analysis: Perform comprehensive analysis of papers ✅
• 📝 Research Prompts: A set of specialized prompts for paper analysis ✅

🚀 Quick Start

Prerequisites

• Python 3.10+
• uv (for the recommended uvx install), or FastMCP installed manually

Recommended: run straight from Git with uvx (no clone, no install)

This fork is packaged so any MCP client can launch it directly from the Git URL — uvx clones the repo, builds the pubmed_mcp_server package and runs its console script:

uvx --from "git+https://github.com/yourname/pubmed-mcp-server.git@<commit-or-tag>" \
    --with "mcp<2" pubmed_mcp_server

As an MCP client config (Claude Desktop, Cursor, Cline, ROCK McpEnv, …):

{
  "mcpServers": {
    "pubmed": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yourname/pubmed-mcp-server.git@<commit-or-tag>",
        "--with",
        "mcp<2",
        "pubmed_mcp_server"
      ]
    }
  }
}

This exposes the search_pubmed_articles tool and requires no API key. @<commit-or-tag> is optional but recommended for reproducible installs — see Use in a sandbox via git+https for how to publish and pin it.

Installation

Installing via Smithery

To install pubmed-mcp-server for Claude Desktop automatically via Smithery:

claude

npx -y @smithery/cli install @JackKuo666/pubmed-mcp-server --client claude

Cursor

Paste the following into Settings → Cursor Settings → MCP → Add new server:

• Mac/Linux

npx -y @smithery/cli@latest run @JackKuo666/pubmed-mcp-server --client cursor --config "{}"

Windsurf

npx -y @smithery/cli@latest install @JackKuo666/pubmed-mcp-server --client windsurf --config "{}"

CLine

npx -y @smithery/cli@latest install @JackKuo666/pubmed-mcp-server --client cline --config "{}"

Note: the Smithery entries above install the upstream package, which still uses the NCBI E-utilities backend. Use the uvx --from git+https://... config above to get this fork's Europe PMC backend.

1. Clone the repository:

   git clone https://github.com/JackKuo666/PubMed-MCP-Server.git
   cd PubMed-MCP-Server
   

2. Install the required dependencies:

   pip install -r requirements.txt
   

📊 Usage

Start the Europe PMC server from a clone:

uvx --from . --with "mcp<2" pubmed_mcp_server

Or start the legacy (NCBI-backed) server:

python pubmed_server.py

Usage with Claude Desktop

Add this configuration to your claude_desktop_config.json:

(Mac OS)

{
  "mcpServers": {
    "pubmed": {
      "command": "python",
      "args": ["-m", "pubmed-mcp-server"]
    }
  }
}

(Windows version):

{
  "mcpServers": {
    "pubmed": {
      "command": "C:\\Users\\YOUR\\PATH\\miniconda3\\envs\\mcp_server\\python.exe",
      "args": ["D:\\code\\YOUR\\PATH\\PubMed-MCP-Server\\pubmed_server.py"],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

Using with Cline

{
  "mcpServers": {
    "pubmed": {
      "command": "bash",
      "args": [
        "-c",
        "source /home/YOUR/PATH/mcp-server-pubmed/.venv/bin/activate && python /home/YOUR/PATH/pubmed-mcp-server.py"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

🛠 MCP Tools

The PubMed MCP Server provides the following tools:

1. search_pubmed_key_words: Search for articles on PubMed using keywords.
2. search_pubmed_advanced: Perform an advanced search for articles on PubMed with multiple parameters.
3. get_pubmed_article_metadata: Fetch metadata for a PubMed article using its PMID.
4. download_pubmed_pdf: Attempt to download the full-text PDF for a PubMed article.
5. deep_paper_analysis: Perform a comprehensive analysis of a PubMed article.

The Europe PMC package (pubmed_mcp_server) exposes:

1. search_pubmed_articles(query, api_key=None): Search articles through Europe PMC.
2. convert_to_pubmed_query (prompt): Turn a natural language question into PubMed search syntax.
3. article://{pmid} (resource): Fetch a single article by PMID.

Searching Papers

You can ask the AI assistant to search for papers using queries like:

Can you search PubMed for recent papers about CRISPR?

Getting Paper Details

Once you have a PMID, you can ask for more details:

Can you show me the metadata for the paper with PMID 12345678?

Analyzing Papers

You can request a deep analysis of a paper:

Can you perform a deep analysis of the paper with PMID 12345678?

📦 Use in a sandbox via git+https

uvx --from <local-path> does not expose tools correctly when run inside the ROCK sandbox (the server starts but lists 0 tools). Publish this repository to Git and install it via git+https instead.

Upload to GitHub

1. Create a new public GitHub repository, e.g. yourname/pubmed-mcp-server.

2. From this project root, push the code:

   git init
   git add pyproject.toml README.md requirements.txt pubmed_mcp_server pubmed_server.py pubmed_web_search.py
   git commit -m "Switch PubMed MCP server backend to Europe PMC"
   git branch -M main
   git remote add origin https://github.com/yourname/pubmed-mcp-server.git
   git push -u origin main
   

3. Note the pushed commit SHA (or create a tag such as v0.0.1) — pin it in the client config so the sandbox always installs a reproducible revision:

   git rev-parse --short HEAD
   # or
   git tag v0.0.1 && git push origin v0.0.1
   

The repository root must contain pyproject.toml and the pubmed_mcp_server/ package (__init__.py, main.py, pubmed.py), which is what the pubmed_mcp_server entry point resolves to.

Config to fill into pubmed/demo.py

PUBMED_SERVER_CONFIG = {
    "command": "uvx",
    "args": [
        "--from",
        "git+https://github.com/yourname/pubmed-mcp-server.git@<commit-or-tag>",
        "--with",
        "mcp<2",
        "pubmed_mcp_server",
    ],
}

Then call the tool:

result = await session.call_tool(
    "search_pubmed_articles", arguments={"query": "cancer immunotherapy"}
)

No API key is required.

📁 Project Structure

• pubmed_mcp_server/pubmed.py: Europe PMC REST search layer (retries, timeouts, JSON parsing)
• pubmed_mcp_server/main.py: FastMCP server exposing search_pubmed_articles
• pubmed_server.py: The original upstream MCP server implementation using FastMCP
• pubmed_web_search.py: The original NCBI E-utilities logic used by pubmed_server.py

🔧 Dependencies

• Python 3.10+
• FastMCP (mcp)
• requests
• asyncio, logging (standard library)
• beautifulsoup4 (only needed for the legacy pubmed_server.py entry point)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License.

⚠️ Disclaimer

This tool is for research purposes only. Please respect PubMed's and Europe PMC's terms of service and use this tool responsibly.

If you need direct NCBI E-utilities access, run the legacy pubmed_server.py outside the sandbox, or use an NCBI API key from an unblocked IP.