pubmed-mcp-server

Pubmed Search Articles

pubmed_search_articles

Read-only

Search PubMed with full query syntax, filters, and date ranges. Returns PMIDs and optional brief summaries. Supports field-specific filters (author, journal, MeSH terms), common filters (language, species, free full text), and pagination via offset for paging through large result sets.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`sort`	No	Sort order: relevance (default), pub_date (newest first), author, or journal	relevance
`query`	Yes	PubMed search query (supports full NCBI syntax). Must carry a search term: a value that is blank once markup, bracketed field tags (`[pdat]`), and parentheses are removed is rejected rather than sent to PubMed as an empty term.
`author`	No	Filter by author name (e.g. "Smith J")
`offset`	No	Result offset for pagination (0-based). PubMed serves at most the first 9999 records of a result set, so this caps at 9998; narrow the query or add filters to reach anything beyond it.
`journal`	No	Filter by journal name
`species`	No	Filter by species
`language`	No	Filter by language (e.g. "english")
`dateRange`	No	Filter by date range. The filter is applied only when both `minDate` and `maxDate` are non-empty; either one empty disables the entire date range.
`meshTerms`	No	Filter by MeSH terms. Multiple terms are AND'd — all must match.
`maxResults`	No	Maximum results to return
`hasAbstract`	No	Only include articles with abstracts
`freeFullText`	No	Only include free full text articles
`summaryCount`	No	Fetch brief summaries for top N results (0 = PMIDs only). Above the 50 cap, pass the remaining PMIDs to pubmed_fetch_articles.
`publicationTypes`	No	Filter by publication type (e.g. "Review", "Clinical Trial", "Meta-Analysis"). Multiple values are OR'd — any match qualifies.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`pmids`	No	PubMed IDs
`query`	No	Original query
`notice`	No	Optional guidance when the result set does not reflect what was asked for — a field tag PubMed ignored, a phrase it matched nothing for, a dateRange dropped for having one bound, no matches at all, or paging past the end. Absent when nothing applies.
`offset`	No	Result offset used
`searchUrl`	No	PubMed search URL
`summaries`	No	Brief summaries (empty array when summaryCount is 0)
`totalCount`	No	Total matching articles
`appliedFilters`	No	Normalized filter values that were applied to the PubMed query
`effectiveQuery`	No	Sanitized query sent to PubMed after applying all active filters

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 23, 2026

changedInput schema / properties / query / description

Previous value: -"PubMed search query (supports full NCBI syntax). Must carry a search term: a value that is blank once markup is stripped is rejected rather than sent to PubMed as an empty term."New value: +"PubMed search query (supports full NCBI syntax). Must carry a search term: a value that is blank once markup, bracketed field tags (`[pdat]`), and parentheses are removed is rejected rather than sent to PubMed as an empty term."

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "query",
-      "offset",
-      "pmids",
-      "summaries",
-      "searchUrl",
-      "effectiveQuery",
-      "totalCount",
-      "appliedFilters"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "query",
+      "offset",
+      "pmids",
+      "summaries",
+      "searchUrl",
+      "totalCount",
+      "effectiveQuery",
+      "appliedFilters"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `queue_full`: The local NCBI request queue shed the call — the queue is full, or the call cannot start before its total deadline (for example behind the cooldown that follows an NCBI 429). `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query holds no search term once whitespace, and any markup the tool strips first, are removed — so NCBI would receive a blank term. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `queue_full`: The local NCBI request queue shed the call — the queue is full, or the call cannot start before its total deadline (for example behind the cooldown that follows an NCBI 429). `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query holds no search term once whitespace, and anything the tool strips before searching, are removed — so NCBI would receive a blank term. pubmed_search_articles strips markup, bracketed field tags, and parentheses, so a bare field tag such as `[pdat]` or empty parentheses `()` count as blank there. Other values are possible when a failure originates below the handler."

Changed1 schema field changedSep 23, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `queue_full`: Local NCBI request queue is at capacity. `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query holds no search term once whitespace, and any markup the tool strips first, are removed — so NCBI would receive a blank term. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `queue_full`: The local NCBI request queue shed the call — the queue is full, or the call cannot start before its total deadline (for example behind the cooldown that follows an NCBI 429). `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query holds no search term once whitespace, and any markup the tool strips first, are removed — so NCBI would receive a blank term. Other values are possible when a failure originates below the handler."

Changed6 schema fields changedSep 11, 2026

changedOutput schema / properties / summaries / items / properties / authors / description

Previous value: -"Formatted author string"New value: +"Formatted author string — the first three of the record's own authors, then \"et al.\". On an NCBI Bookshelf chapter these are the chapter's authors; the book's editors are reported separately in `editors`."

addedOutput schema / properties / summaries / items / properties / bookTitle

Added value: +{
+  "description": "Title of the book an NCBI Bookshelf record belongs to, e.g. \"GeneReviews(®)\". Present instead of `source` on a book record; absent on a journal article.",
+  "type": "string"
+}

addedOutput schema / properties / summaries / items / properties / docType

Added value: +{
+  "description": "What PubMed classifies this record as: \"chapter\" or \"book\" for an NCBI Bookshelf record, \"citation\" for an ordinary journal article. Absent when PubMed supplies none.",
+  "type": "string"
+}

addedOutput schema / properties / summaries / items / properties / editors

Added value: +{
+  "description": "Editors of the containing book, kept out of `authors` so they cannot displace the record's own authors. Absent on a journal article and on a book that credits no editors.",
+  "items": {
+    "description": "One editor, \"Surname Initials\" as ESummary renders it",
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / summaries / items / properties / publisherName

Added value: +{
+  "description": "Publisher of the book an NCBI Bookshelf record belongs to. Present only on a book record; absent on a journal article.",
+  "type": "string"
+}

changedOutput schema / properties / summaries / items / properties / source / description

Previous value: -"Journal source"New value: +"Journal the article appeared in. Absent on an NCBI Bookshelf record, which has no journal — its venue is in `bookTitle` and `publisherName` instead, and `docType` says which kind of record it is."

Changed3 schema fields changedSep 11, 2026

changedInput schema / properties / query / description

Previous value: -"PubMed search query (supports full NCBI syntax)"New value: +"PubMed search query (supports full NCBI syntax). Must carry a search term: a value that is blank once markup is stripped is rejected rather than sent to PubMed as an empty term."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `queue_full`: Local NCBI request queue is at capacity. `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `queue_full`: Local NCBI request queue is at capacity. `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query holds no search term once whitespace, and any markup the tool strips first, are removed — so NCBI would receive a blank term. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "queue_full",
-  "ncbi_unreachable",
-  "ncbi_deadline_exceeded",
-  "ncbi_invalid_response",
-  "ncbi_resource_not_found"
-]New value: +[
+  "queue_full",
+  "ncbi_unreachable",
+  "ncbi_deadline_exceeded",
+  "ncbi_invalid_response",
+  "ncbi_resource_not_found",
+  "blank_query"
+]

Changed6 schema fields changedAug 21, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "query",
+      "offset",
+      "pmids",
+      "summaries",
+      "searchUrl",
+      "effectiveQuery",
+      "totalCount",
+      "appliedFilters"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `queue_full`: Local NCBI request queue is at capacity. `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "queue_full",
+            "ncbi_unreachable",
+            "ncbi_deadline_exceeded",
+            "ncbi_invalid_response",
+            "ncbi_resource_not_found"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "query",
-  "offset",
-  "pmids",
-  "summaries",
-  "searchUrl",
-  "effectiveQuery",
-  "totalCount",
-  "appliedFilters"
-]

Changed5 schema fields changedJul 26, 2026

changedInput schema / properties / offset / description

Previous value: -"Result offset for pagination (0-based)"New value: +"Result offset for pagination (0-based). PubMed serves at most the first 9999 records of a result set, so this caps at 9998; narrow the query or add filters to reach anything beyond it."

changedInput schema / properties / offset / maximum

Previous value: -9007199254740991New value: +9998

changedInput schema / properties / summaryCount / description

Previous value: -"Fetch brief summaries for top N results (0 = PMIDs only)"New value: +"Fetch brief summaries for top N results (0 = PMIDs only). Above the 50 cap, pass the remaining PMIDs to pubmed_fetch_articles."

changedOutput schema / properties / notice / description

Previous value: -"Optional guidance when results are empty or paging overshot — e.g. how to broaden filters or reset offset. Absent on successful result pages."New value: +"Optional guidance when the result set does not reflect what was asked for — a field tag PubMed ignored, a phrase it matched nothing for, a dateRange dropped for having one bound, no matches at all, or paging past the end. Absent when nothing applies."

changedOutput schema / properties / summaries / items / properties / doi / description

Previous value: -"DOI"New value: +"DOI, cased as NCBI reports it. DOIs are case-insensitive by spec and no case normalization is applied here, so casing can differ from a Europe PMC-sourced `doi` — compare the two case-insensitively."

Changed3 schema fields changedJun 11, 2026

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Total matching articles",
+  "type": "number"
+}

removedOutput schema / properties / totalFound

Removed value: -{
-  "description": "Total matching articles",
-  "type": "number"
-}

changedOutput schema / required

Previous value: -[
-  "query",
-  "offset",
-  "pmids",
-  "summaries",
-  "searchUrl",
-  "effectiveQuery",
-  "totalFound",
-  "appliedFilters"
-]New value: +[
+  "query",
+  "offset",
+  "pmids",
+  "summaries",
+  "searchUrl",
+  "effectiveQuery",
+  "totalCount",
+  "appliedFilters"
+]

Changed1 schema field changedMay 30, 2026

changedOutput schema / required

Previous value: -[
-  "query",
-  "effectiveQuery",
-  "appliedFilters",
-  "totalFound",
-  "offset",
-  "pmids",
-  "summaries",
-  "searchUrl"
-]New value: +[
+  "query",
+  "offset",
+  "pmids",
+  "summaries",
+  "searchUrl",
+  "effectiveQuery",
+  "totalFound",
+  "appliedFilters"
+]

Changed3 schema fields changedApr 27, 2026

changedInput schema / properties / dateRange / description

Previous value: -"Filter by date range"New value: +"Filter by date range. The filter is applied only when both `minDate` and `maxDate` are non-empty; either one empty disables the entire date range."

changedInput schema / properties / dateRange / properties / maxDate / description

Previous value: -"End date (YYYY/MM/DD, YYYY/MM, or YYYY)"New value: +"End date (YYYY/MM/DD, YYYY/MM, or YYYY); empty string disables this bound"

changedInput schema / properties / dateRange / properties / minDate / description

Previous value: -"Start date (YYYY/MM/DD, YYYY/MM, or YYYY)"New value: +"Start date (YYYY/MM/DD, YYYY/MM, or YYYY); empty string disables this bound"

Changed1 schema field changedApr 24, 2026
- addedOutput schema / properties / summaries / items / description
```
Added value: +"Brief article summary"
```

Changed5 schema fields changedApr 20, 2026

addedInput schema / properties / dateRange / properties / maxDate / pattern
```
Added value: +"^$|^\\d{4}([/\\-.]\\d{1,2}([/\\-.]\\d{1,2})?)?$"
```
addedInput schema / properties / dateRange / properties / minDate / pattern
```
Added value: +"^$|^\\d{4}([/\\-.]\\d{1,2}([/\\-.]\\d{1,2})?)?$"
```

changedInput schema / properties / meshTerms / description

Previous value: -"Filter by MeSH terms"New value: +"Filter by MeSH terms. Multiple terms are AND'd — all must match."

changedInput schema / properties / publicationTypes / description

Previous value: -"Filter by publication type (e.g. \"Review\", \"Clinical Trial\", \"Meta-Analysis\")"New value: +"Filter by publication type (e.g. \"Review\", \"Clinical Trial\", \"Meta-Analysis\"). Multiple values are OR'd — any match qualifies."

addedOutput schema / properties / notice

Added value: +{
+  "description": "Optional guidance when results are empty or paging overshot — e.g. how to broaden filters or reset offset. Absent on successful result pages.",
+  "type": "string"
+}

Changed3 schema fields changedApr 9, 2026

addedOutput schema / properties / appliedFilters

Added value: +{
+  "additionalProperties": false,
+  "description": "Normalized filter values that were applied to the PubMed query",
+  "properties": {
+    "author": {
+      "description": "Author filter applied to the search",
+      "type": "string"
+    },
+    "dateRange": {
+      "additionalProperties": false,
+      "description": "Date range filter applied to the search",
+      "properties": {
+        "dateType": {
+          "description": "Applied date field used for the range filter",
+          "enum": [
+            "pdat",
+            "mdat",
+            "edat"
+          ],
+          "type": "string"
+        },
+        "maxDate": {
+          "description": "Applied maximum date",
+          "type": "string"
+        },
+        "minDate": {
+          "description": "Applied minimum date",
+          "type": "string"
+        }
+      },
+      "required": [
+        "minDate",
+        "maxDate",
+        "dateType"
+      ],
+      "type": "object"
+    },
+    "freeFullText": {
+      "description": "Whether results were restricted to free full-text articles",
+      "type": "boolean"
+    },
+    "hasAbstract": {
+      "description": "Whether results were restricted to articles with abstracts",
+      "type": "boolean"
+    },
+    "journal": {
+      "description": "Journal filter applied to the search",
+      "type": "string"
+    },
+    "language": {
+      "description": "Language filter applied to the search",
+      "type": "string"
+    },
+    "meshTerms": {
+      "description": "MeSH term filters applied to the search",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "publicationTypes": {
+      "description": "Publication type filters applied to the search",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "species": {
+      "description": "Species filter applied to the search",
+      "enum": [
+        "humans",
+        "animals"
+      ],
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

addedOutput schema / properties / effectiveQuery

Added value: +{
+  "description": "Sanitized query sent to PubMed after applying all active filters",
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "query",
-  "totalFound",
-  "offset",
-  "pmids",
-  "summaries",
-  "searchUrl"
-]New value: +[
+  "query",
+  "effectiveQuery",
+  "appliedFilters",
+  "totalFound",
+  "offset",
+  "pmids",
+  "summaries",
+  "searchUrl"
+]

Changed2 schema fields changedApr 1, 2026
- changedInput schema / properties / dateRange / properties / maxDate / description
```
Previous value: -"End date (YYYY-MM-DD)"New value: +"End date (YYYY/MM/DD, YYYY/MM, or YYYY)"
```
- changedInput schema / properties / dateRange / properties / minDate / description
```
Previous value: -"Start date (YYYY-MM-DD)"New value: +"Start date (YYYY/MM/DD, YYYY/MM, or YYYY)"
```
First observedMar 23, 2026

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds valuable behavioral context beyond the annotations. It discloses that the tool 'Returns PMIDs and optional brief summaries,' explains the offset cap ('PubMed serves at most the first 9999 records'), and clarifies the dateRange behavior ('the filter is applied only when both minDate and maxDate are non-empty'). These are not present in the annotations (readOnlyHint and openWorldHint) and help the agent understand side effects and limitations. No contradictions with annotations.

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?

The description is two sentences, front-loaded with the primary purpose, and uses compact but informative language. It covers the main capabilities without redundancy, and each phrase adds value (e.g., 'full query syntax', 'optional brief summaries', 'pagination'). It is well-structured and easy to parse.

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?

Given the tool has 14 parameters and an output schema, the description is reasonably complete. It summarizes key features (filters, pagination, summaries) but does not enumerate all parameter types; however, the schema provides full details. It also explains critical limits (offset cap, summaryCount cap) that an agent needs to know. The presence of an output schema reduces the need to describe return values, so a 4 is appropriate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the baseline is 3. The tool description mostly restates what the schema already documents (e.g., 'pagination via offset' aligns with the offset parameter's description). It does not add new meaning to parameters; the only added value is the summaryCount routing note, which is already in the schema. Therefore, it does not exceed the baseline.

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's function: 'Search PubMed with full query syntax, filters, and date ranges.' It specifies the resource (PubMed), the action (search), and the scope (full query syntax, filters, date ranges), and distinguishes itself from sibling tools like pubmed_fetch_articles by focusing on search and returning PMIDs/summaries rather than full articles. The mention of 'field-specific filters' and 'pagination' further clarifies its role.

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 description does not explicitly state when to use this tool versus siblings, but it implies its role as a search tool through the phrase 'Search PubMed.' It does provide a specific routing hint in the summaryCount parameter description: 'Above the 50 cap, pass the remaining PMIDs to pubmed_fetch_articles.' However, there is no explicit statement of exclusions or alternatives for the overall search task, so it falls short of a perfect 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All pubmed-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Pubmed Search Articles

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources