mcp-pubmed
Gives access to PubMed and PubMed Central via the NCBI E-utilities API, enabling keyword and author searches, retrieval of article metadata and abstracts, full-text downloads for open-access articles, and discovery of related research publications.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-pubmedsearch for recent meta-analyses on SGLT2 inhibitors and heart failure"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-pubmed
A Model Context Protocol (MCP) server that gives Claude (or any MCP-compatible AI) direct access to PubMed and PubMed Central via the free NCBI E-utilities API.
No subscription required. No third-party service. Pure NCBI.
Features
Tool | Description |
| Search articles by keyword, with filters for date range, article type, and sort order. Supports full PubMed query syntax. |
| Retrieve complete metadata for a single article by PMID (abstract, authors, MeSH terms, keywords, DOI, PMC link). |
| Download the full text from PubMed Central when the article is open-access. |
| Find articles related to a given PMID using NCBI's similarity algorithm. |
| List all articles published by a specific author, sorted by most recent. |
Related MCP server: BioContextAI Knowledgebase MCP
Requirements
Python 3.11 or higher
pip
Installation
1 — Clone the repository
git clone https://github.com/benoitleq/mcp-pubmed.git
cd mcp-pubmed2 — Create a virtual environment
python -m venv .venvActivate it:
Windows (PowerShell) :
.venv\Scripts\Activate.ps1Windows (CMD) :
.venv\Scripts\activate.batmacOS / Linux :
source .venv/bin/activate
3 — Install dependencies
pip install -r requirements.txt4 — (Optional) Set your NCBI API key
Without a key the NCBI API is limited to 3 requests/second. With a free key you get 10 requests/second.
Get your key at https://www.ncbi.nlm.nih.gov/account/ → Settings → API Key Management.
Copy the example env file and add your key:
cp .env.example .env
# then edit .env and uncomment the NCBI_API_KEY lineOr set it directly in your shell:
export NCBI_API_KEY=your_key_here # macOS / Linux
$env:NCBI_API_KEY = "your_key_here" # Windows PowerShellConfigure Claude Desktop
Edit claude_desktop_config.json (location depends on your OS):
OS | Path |
Windows |
|
macOS |
|
Linux |
|
Add the following block inside the "mcpServers" object:
{
"mcpServers": {
"pubmed": {
"command": "python",
"args": ["C:/path/to/mcp-pubmed/main.py"],
"env": {
"NCBI_API_KEY": "your_key_here"
}
}
}
}Windows tip: use forward slashes or double backslashes in the path. If
pythonis not on your PATH, use the full path to your virtual environment:"C:/path/to/mcp-pubmed/.venv/Scripts/python.exe"
Restart Claude Desktop. You should see the 5 PubMed tools available.
Configure Claude Code (VS Code / CLI)
Run this command from the project root:
claude mcp add pubmed python main.pyOr add it manually to your Claude Code settings (.claude/settings.json):
{
"mcpServers": {
"pubmed": {
"command": "python",
"args": ["main.py"],
"env": {
"NCBI_API_KEY": "your_key_here"
}
}
}
}Usage examples
Once connected, just ask Claude naturally:
Search for recent meta-analyses on SGLT2 inhibitors and heart failure.
Find the 5 latest meta-analyses on metformin and cancer.
Find all articles published by Topol EJ since 2020.
Get the abstract for PMID 33982811.
Is the full text of PMID 34591945 available?
Find articles related to PMID 31475795.PubMed query syntax
The search_pubmed tool accepts standard PubMed query syntax:
Example | Meaning |
| Exact MeSH term |
| Word in title or abstract |
| Articles by author |
| Publication date range |
| Filter by publication type |
| Boolean operators |
Rate limits
Situation | Limit |
No API key | 3 requests / second |
With API key | 10 requests / second |
The server handles 429 rate-limit errors and 5xx server errors automatically with up to 3 retries and exponential back-off.
Project structure
mcp-pubmed/
├── main.py # MCP server — all tools defined here
├── requirements.txt # Python dependencies
├── pyproject.toml # Package metadata
├── .env.example # Environment variable template
└── README.mdHow it works
Claude ──MCP── main.py ──HTTPS── NCBI E-utilities API
├── esearch.fcgi (search)
├── efetch.fcgi (fetch records / full text)
└── elink.fcgi (related articles)Claude calls a tool (e.g.
search_pubmed).main.pybuilds a request to the appropriate NCBI endpoint.The XML/JSON response is parsed and formatted as plain text.
Claude receives the result and presents it to you.
MCP vs Skill — which approach to choose?
There are two ways to give Claude access to PubMed:
This project — an MCP server (Python process, explicit tools)
A Skill — a Markdown prompt file that instructs Claude to call the NCBI API directly via its built-in
web_fetchcapability (see e.g. pubmed-skill)
Comparison
MCP (this project) | Skill (prompt file) | |
Setup | Python 3.11 + venv + dependencies + config in | Copy one |
Maintenance | Server process to start and keep running | Nothing to maintain |
Portability | Must be configured in every Claude client | Works anywhere Claude has web access |
Reliability | Deterministic — explicit retry logic, error handling, XML parsing | Depends on Claude's interpretation of the prompt |
Power | Full control: pagination, caching, auth, complex post-processing | Limited to what Claude can do in a single prompt turn |
Sharing | Distributable as a Python package or Docker image | Just share the |
Auditability | Code is explicit, testable, versionable | Behavior may vary across Claude versions |
When to choose MCP
You need guaranteed, reproducible behavior on every call
You are building a tool for a team or an application (not just personal use)
You need complex logic: pagination, caching, structured output, authentication
You want to expose PubMed to non-Claude clients via the MCP standard
When to choose a Skill
Personal use in Claude Desktop or Claude Code — you just want it to work
You want zero friction: no installation, no configuration, no process to manage
The task is occasional and correctness variations are acceptable
Bottom line
For solo use, a Skill is simpler and good enough. For production, teams, or complex workflows, MCP is more robust.
Troubleshooting
"No module named mcp"
→ Make sure your virtual environment is activated and you ran pip install -r requirements.txt.
"Could not connect to NCBI"
→ Check your internet connection. NCBI is at eutils.ncbi.nlm.nih.gov.
Rate limit errors (429) → Add an NCBI API key (see above).
Claude does not see the tools
→ Check that the path in claude_desktop_config.json is absolute and correct.
→ Restart Claude Desktop after any config change.
License
MIT — free for personal and commercial use.
Acknowledgements
Built on the NCBI E-utilities API (free, no subscription required) and the Model Context Protocol by Anthropic.
Available Tools
5 toolsget_articleA
Get complete details of a PubMed article by its PMID.
Args: pmid: The PubMed ID (numeric string), e.g. "33982811".
Returns: Full article metadata: title, all authors, journal, date, DOI, PMC link, publication types, full abstract, keywords, MeSH terms. Returns an error message if the PMID is invalid or not found.
| Name | Required | Description | Default |
|---|---|---|---|
| pmid | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and successfully discloses error behavior ('Returns an error message if the PMID is invalid or not found'). Lacks mention of rate limits or authentication requirements, but covers the critical failure mode.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Uses a structured docstring format (Args/Returns) with zero waste. The first sentence establishes purpose, followed by precise parameter documentation and return value specification. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter lookup tool, the description is comprehensive: it documents the input parameter (compensating for schema gaps), lists return fields, and specifies error behavior. Presence of output schema reduces the need for detailed return documentation, yet it provides helpful field enumeration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (parameter has no description field), but the description fully compensates by documenting the PMID parameter with semantics ('PubMed ID'), format hint ('numeric string'), and a concrete example ('33982811').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with specific verb ('Get'), resource ('PubMed article'), and scope ('complete details by its PMID'), clearly distinguishing it from sibling search tools and full-text retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by its PMID' provides clear context that this tool requires a specific identifier, implicitly distinguishing it from search_pubmed and search_by_author siblings. However, it does not explicitly name alternatives or state when to use search vs. retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_full_textA
Retrieve the full text of an article from PubMed Central (PMC) if available.
Only open-access articles archived in PMC have a full text. Subscription-only articles will return a link to PubMed instead.
Args: pmid: The PubMed ID of the article.
Returns: The full text (title, abstract, and body sections) when the article is open-access in PMC, or a helpful message with links otherwise.
| Name | Required | Description | Default |
|---|---|---|---|
| pmid | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and successfully discloses dual-output behavior (full text with structure 'title, abstract, and body sections' vs 'helpful message with links'), and the PMC open-access constraint. Lacks mention of rate limits, caching, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Uses standard docstring format (Args/Returns) that is appropriate for the documentation burden. Every sentence serves a distinct purpose: capability statement, constraint warning, fallback behavior, parameter definition, and return value specification. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with conditional output logic, the description is comprehensive. It explains the parameter (since schema fails to), documents both success and failure response patterns, and clarifies content scope (PMC open-access only) without needing to duplicate the output schema structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Compensates effectively for 0% schema description coverage by defining the 'pmid' parameter as 'The PubMed ID of the article,' providing essential semantic mapping. Would benefit from format hints (e.g., numeric string) or validation constraints to achieve a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Retrieve') and resource ('full text of an article from PubMed Central'), clearly distinguishing it from siblings like 'get_article' (likely metadata) and 'search_pubmed' (discovery). The 'if available' qualifier immediately signals the conditional nature of this operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly defines scope limitations ('Only open-access articles archived in PMC') and failure mode behavior ('Subscription-only articles will return a link'), guiding users on when the tool will and won't return full text. Lacks explicit cross-reference to sibling tools (e.g., 'use get_article for metadata-only retrieval').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_by_authorA
Search PubMed for all articles by a specific author.
Args: author: Author name in PubMed format. Examples: "Smith JA" (last name + initials — most precise) "Smith J" (last name + first initial) "John Smith" (full name, less reliable) max_results: Number of results to return (1-100, default 10). year_from: Restrict to articles published from this year. year_to: Restrict to articles published up to this year.
Returns: A list of articles by the author, sorted by most recent first. Returns an error message if the author name is empty or the query fails.
| Name | Required | Description | Default |
|---|---|---|---|
| author | Yes | ||
| max_results | No | ||
| year_from | No | ||
| year_to | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It successfully discloses sorting behavior ('sorted by most recent first') and error conditions ('Returns an error message if the author name is empty'). Lacks only details on pagination or rate limiting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Efficiently structured with clear Args/Returns sections. Every element serves a purpose: examples clarify PubMed naming conventions, ranges prevent invalid inputs, and the Returns section sets expectations. No redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a 4-parameter search tool. Despite existing output schema (not shown), the description adds essential behavioral context (sorting order, error formats) that schemas typically don't convey. Fully covers all parameters given the zero schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Excellent compensation for 0% schema coverage. The Args section provides detailed semantics: three concrete format examples for 'author' (Smith JA, Smith J, John Smith), valid range for 'max_results' (1-100, default 10), and clear temporal semantics for year filters ('from this year', 'up to this year').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with specific verb+resource: 'Search PubMed for all articles by a specific author.' The phrase 'by a specific author' clearly distinguishes this from the sibling tool 'search_pubmed' (general search) and positions it as the correct choice for author-specific queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context through the specificity of 'by a specific author,' implying the exact use case (author-based retrieval). However, it lacks explicit 'when not to use' guidance or explicit comparison to 'search_pubmed' for broader queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_pubmedA
Search PubMed for articles matching a query.
Args: query: Search query. Supports full PubMed syntax: AND / OR / NOT, field tags like [tiab], [MeSH], [au], etc. Examples: "covid-19 vaccine efficacy" "myocardial infarction[MeSH] AND aspirin[tiab]" max_results: Number of articles to return (1-100, default 10). year_from: Restrict results to articles published from this year. year_to: Restrict results to articles published up to this year. article_type: Filter by publication type, e.g. "Review", "Clinical Trial", "Meta-Analysis", "Randomized Controlled Trial". sort: "relevance" (default) or "date" (most recent first).
Returns: A formatted list of matching articles with PMID, title, authors, journal, date, and a short abstract snippet. Returns an error message if the query fails or yields no results.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| max_results | No | ||
| year_from | No | ||
| year_to | No | ||
| article_type | No | ||
| sort | No | relevance |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure and succeeds by detailing the return format as 'a formatted list of matching articles with PMID, title, authors, journal, date, and a short abstract snippet.' It also discloses error handling behavior, noting it returns an error message if the query fails or yields no results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses a clear structured format with Args and Returns sections, and every line provides valuable information such as PubMed syntax examples and field tags. While lengthy, the examples are essential given the complexity of PubMed search syntax, making the length appropriate rather than wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the zero percent schema coverage and lack of annotations, the description is remarkably complete by documenting all input parameters with examples and explaining the output structure in the Returns section. No significant gaps remain for an agent to successfully invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description comprehensively documents all six parameters through the Args section, including syntax examples for the query parameter, valid ranges for max_results, and allowed values for article_type and sort. This fully compensates for the complete lack of schema metadata.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Search PubMed for articles matching a query,' providing a specific verb and resource. It implicitly distinguishes itself from sibling tools like get_article (which likely retrieves by ID) and search_by_author by emphasizing query-based matching rather than specific ID retrieval or author searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description explains how to construct queries using PubMed syntax, it lacks explicit guidance on when to use this tool versus siblings like search_by_author. The Args section implies usage through examples but does not explicitly state when to choose this over alternative search methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.1.0- First observed
get_article - First observed
get_full_text - First observed
get_related_articles - First observed
search_by_author - First observed
search_pubmed
TDQS
Scored across 5 tools
Each tool serves a distinctly different purpose: retrieving metadata (get_article), fetching full text (get_full_text), discovering related papers (get_related_articles), and two different search modes (general query vs. specific author lookup). No functional overlap exists that would confuse an agent about which to select.
Tools mostly follow a clear verb_noun pattern in snake_case (get_article, get_full_text, search_pubmed). The minor deviation is search_by_author which uses a preposition ('by') while search_pubmed does not, creating a slight inconsistency in how search specialization is indicated.
Five tools is an ideal, tight scope for a PubMed server. It covers the essential lifecycle—searching (general and by author), retrieving metadata, accessing full text, and discovering related articles—without unnecessary bloat or fragmentation.
The set provides solid read-only coverage for PubMed workflows: search capabilities, detailed retrieval, and discovery via related articles. Minor gap: lacks citation lookup (finding articles that cite a given PMID), a common PubMed feature, but core research workflows are well-supported.
Maintenance
Related MCP Connectors
Auditable MCP server for PubMed, Europe PMC, ClinicalTrials.gov, and bioRxiv/medRxiv queries
PubMed MCP — wraps the NCBI E-utilities API (biomedical literature, free, no auth)
Search biomedical literature, get article details, find related articles, and explore MeSH terms
Academic research MCP server for paper search, citation checks, graphs, and deep research.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenance🔍 Enable AI assistants to search, access, and analyze PubMed articles through a simple MCP interface.129MIT
- AlicenseBqualityCmaintenanceAn MCP server that provides standardized access to biomedical knowledge bases and resources, enabling AI systems to retrieve verified information from sources like bioRxiv, EuropePMC, and various protein/gene databases.5228Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that provides access to PubMed and NCBI's biomedical literature database for searching articles, retrieving metadata, and tracking citations. It enables users to explore related research, browse MeSH vocabulary, and find free full-text links.6MIT
- AlicenseNot gradedqualityDmaintenanceA specialized MCP server that provides a structured interface to the Europe PMC database for biological and clinical evidence retrieval. It enables LLMs to gather, rank, and synthesize published research focusing on therapeutic targets and disease associations.1MIT