Skip to main content
Glama

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_pubmed

Search articles by keyword, with filters for date range, article type, and sort order. Supports full PubMed query syntax.

get_article

Retrieve complete metadata for a single article by PMID (abstract, authors, MeSH terms, keywords, DOI, PMC link).

get_full_text

Download the full text from PubMed Central when the article is open-access.

get_related_articles

Find articles related to a given PMID using NCBI's similarity algorithm.

search_by_author

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-pubmed

2 — Create a virtual environment

python -m venv .venv

Activate it:

  • Windows (PowerShell) : .venv\Scripts\Activate.ps1

  • Windows (CMD) : .venv\Scripts\activate.bat

  • macOS / Linux : source .venv/bin/activate

3 — Install dependencies

pip install -r requirements.txt

4 — (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 line

Or set it directly in your shell:

export NCBI_API_KEY=your_key_here      # macOS / Linux
$env:NCBI_API_KEY = "your_key_here"   # Windows PowerShell

Configure Claude Desktop

Edit claude_desktop_config.json (location depends on your OS):

OS

Path

Windows

%APPDATA%\Claude\claude_desktop_config.json

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

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 python is 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.py

Or 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

"heart failure"[MeSH]

Exact MeSH term

metformin[tiab]

Word in title or abstract

Smith J[au]

Articles by author

2020:2024[pdat]

Publication date range

"Randomized Controlled Trial"[pt]

Filter by publication type

AND, OR, NOT

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.md

How it works

Claude ──MCP── main.py ──HTTPS── NCBI E-utilities API
                                 ├── esearch.fcgi  (search)
                                 ├── efetch.fcgi   (fetch records / full text)
                                 └── elink.fcgi    (related articles)
  1. Claude calls a tool (e.g. search_pubmed).

  2. main.py builds a request to the appropriate NCBI endpoint.

  3. The XML/JSON response is parsed and formatted as plain text.

  4. 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:

  1. This project — an MCP server (Python process, explicit tools)

  2. A Skill — a Markdown prompt file that instructs Claude to call the NCBI API directly via its built-in web_fetch capability (see e.g. pubmed-skill)

Comparison

MCP (this project)

Skill (prompt file)

Setup

Python 3.11 + venv + dependencies + config in claude_desktop_config.json

Copy one .md file — done

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 .md file

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 tools
get_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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pmidYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pmidYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
authorYes
max_resultsNo
year_fromNo
year_toNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
max_resultsNo
year_fromNo
year_toNo
article_typeNo
sortNorelevance

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

  1. 5 tool updatesv0.1.0
    • First observedget_article
    • First observedget_full_text
    • First observedget_related_articles
    • First observedsearch_by_author
    • First observedsearch_pubmed

TDQS

A4.4/5.0

Scored across 5 tools

Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    D
    maintenance
    An 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.
    6
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    A 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.
    1
    MIT