@cyanheads/pubmed-mcp-server

MCP server for the NCBI E-utilities API. Search PubMed, fetch article metadata and full text, generate citations, explore MeSH terms, and discover related research. STDIO or Streamable HTTP.

7 Tools • 1 Resource • 1 Prompt

Public Hosted Server: https://pubmed.caseyjhand.com/mcp

Tools

Seven tools for working with PubMed and NCBI data:

Tool	Description
`pubmed_search_articles`	Search PubMed with full query syntax, field-specific filters, date ranges, pagination, and optional brief summaries
`pubmed_fetch_articles`	Fetch full article metadata by PMIDs — abstract, authors, journal, MeSH terms, grants
`pubmed_fetch_fulltext`	Fetch full-text articles from PubMed Central — body sections, references, and metadata for open-access articles
`pubmed_format_citations`	Generate formatted citations in APA 7th, MLA 9th, BibTeX, or RIS
`pubmed_find_related`	Find similar articles, citing articles, or references for a given PMID
`pubmed_spell_check`	Spell-check biomedical queries using NCBI's ESpell service
`pubmed_lookup_mesh`	Search and explore MeSH vocabulary — tree numbers, scope notes, entry terms

`pubmed_search_articles`

Search PubMed with full NCBI query syntax and filters.

Free-text queries with PubMed's full boolean and field-tag syntax
Field-specific filters: author, journal, MeSH terms, language, species
Common filters: has abstract, free full text
Date range filtering by publication, modification, or Entrez date
Publication type filtering (Review, Clinical Trial, Meta-Analysis, etc.)
Sort by relevance, publication date, author, or journal
Pagination via offset for paging through large result sets
Optional brief summaries for top N results via ESummary

`pubmed_fetch_articles`

Fetch full article metadata by PubMed IDs.

Batch fetch up to 200 articles at once (auto-switches to POST for large batches)
Returns structured data: title, abstract, authors with deduplicated affiliations, journal info, DOI
Direct links to PubMed and PubMed Central (when available)
Optional MeSH terms, grant information, and publication types
Handles PubMed's inconsistent XML (structured abstracts, missing fields, varying date formats)

`pubmed_fetch_fulltext`

Fetch full-text articles from PubMed Central (PMC).

Accepts PMC IDs directly or PubMed IDs (auto-resolved to PMCIDs via ELink)
Returns complete article body text organized by sections and subsections
Optional reference list from back matter
Section filtering by title (case-insensitive match, e.g. ["methods", "results"])
Configurable max sections to limit response size
Up to 10 articles per request
Only open-access articles available in PMC will return full text

`pubmed_format_citations`

Generate formatted citations for articles.

Four citation styles: APA 7th, MLA 9th, BibTeX, RIS
Request multiple styles per article in a single call
Hand-rolled formatters — zero external dependencies, fully Workers-compatible
Up to 50 articles per request

`pubmed_find_related`

Find articles related to a source article via ELink.

Three relationship types: similar (content similarity), cited_by, references
Results enriched with title, authors, publication date, and source via ESummary
Similarity scores included for similar relationship type

`pubmed_spell_check`

Spell-check a biomedical query using NCBI's ESpell.

Returns the original query, corrected query, and whether a suggestion was found
Useful for query refinement before searching

`pubmed_lookup_mesh`

Search and explore the MeSH (Medical Subject Headings) vocabulary.

Search MeSH terms by name with exact-heading matching
Detailed records with tree numbers, scope notes, and entry terms by default
Useful for building precise PubMed queries with controlled vocabulary

Resource and prompt

Type	Name	Description
Resource	`pubmed://database/info`	PubMed database metadata via EInfo (field list, record count, last update)
Prompt	`research_plan`	Generate a structured 4-phase biomedical research plan outline

Features

Built on @cyanheads/mcp-ts-core:

Declarative tool definitions — single file per tool, framework handles registration and validation
Unified error handling across all tools
Pluggable auth (none, jwt, oauth)
Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
Structured logging with optional OpenTelemetry tracing
Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

PubMed-specific:

Complete NCBI E-utilities integration (ESearch, EFetch, ESummary, ELink, ESpell, EInfo)
Sequential request queue with configurable delay for NCBI rate limit compliance
NCBI-specific XML parser with isArray hints for PubMed's inconsistent XML structure
Hand-rolled citation formatters (APA, MLA, BibTeX, RIS) — zero deps, Workers-compatible

Getting started

Public Hosted Instance

A public instance is available at https://pubmed.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "pubmed": {
      "type": "streamable-http",
      "url": "https://pubmed.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "pubmed": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/pubmed-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NCBI_API_KEY": "your-key-here"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "pubmed": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/pubmed-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NCBI_API_KEY": "your-key-here"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "pubmed": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/pubmed-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.3.2 or higher.
Optional: NCBI API key for higher rate limits (10 req/s vs 3 req/s).

Installation

Clone the repository:

git clone https://github.com/cyanheads/pubmed-mcp-server.git

Navigate into the directory:

cd pubmed-mcp-server

Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

Variable	Description	Default
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`	`stdio`
`MCP_HTTP_PORT`	HTTP server port	`3010`
`MCP_AUTH_MODE`	Authentication: `none`, `jwt`, or `oauth`	`none`
`MCP_LOG_LEVEL`	Log level (`debug`, `info`, `warning`, `error`, etc.)	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`<project-root>/logs`
`STORAGE_PROVIDER_TYPE`	Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`	`in-memory`
`NCBI_API_KEY`	NCBI API key for higher rate limits (10 req/s vs 3 req/s)	none
`NCBI_ADMIN_EMAIL`	Contact email sent with NCBI requests (recommended by NCBI)	none
`NCBI_REQUEST_DELAY_MS`	Delay between NCBI requests in ms	334 (100 with key)
`NCBI_MAX_RETRIES`	Retry attempts for failed NCBI requests	3
`NCBI_TIMEOUT_MS`	NCBI request timeout in ms	`30000`
`OTEL_ENABLED`	Enable OpenTelemetry	`false`

Running the server

Local development

Build and run the production version:

# One-time build
bun run rebuild

# Run the built server
bun run start:http
# or
bun run start:stdio

Run checks and tests:

bun run devcheck  # Lints, formats, type-checks, and more
bun run test      # Runs the test suite

Project structure

Directory	Purpose
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`). Seven PubMed tools.
`src/mcp-server/resources`	Resource definitions. Database info resource.
`src/mcp-server/prompts`	Prompt definitions. Research plan prompt.
`src/services/ncbi`	NCBI E-utilities service layer — API client, queue, parser, formatter.
`src/config`	Server-specific environment variable parsing and validation with Zod.
`tests/`	Unit and integration tests, mirroring the `src/` structure.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for logging, ctx.state for storage
Register new tools and resources in the createApp() arrays

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 179 Commits
.github		.github
.vscode		.vscode
docs		docs
schemas/ncbi-dtd		schemas/ncbi-dtd
scripts		scripts
skills		skills
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
bun.lock		bun.lock
bunfig.toml		bunfig.toml
devcheck.config.json		devcheck.config.json
package.json		package.json
server.json		server.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

@cyanheads/pubmed-mcp-server

Tools

`pubmed_search_articles`

`pubmed_fetch_articles`

`pubmed_fetch_fulltext`

`pubmed_format_citations`

`pubmed_find_related`

`pubmed_spell_check`

`pubmed_lookup_mesh`

Resource and prompt

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Project structure

Development guide

Contributing

License

About

Uh oh!

Releases

Sponsor this project

Uh oh!

Packages

Uh oh!

Uh oh!

Contributors 1

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

@cyanheads/pubmed-mcp-server

Tools

pubmed_search_articles

pubmed_fetch_articles

pubmed_fetch_fulltext

pubmed_format_citations

pubmed_find_related

pubmed_spell_check

pubmed_lookup_mesh

Resource and prompt

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Project structure

Development guide

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Uh oh!

Contributors 1

Languages

`pubmed_search_articles`

`pubmed_fetch_articles`

`pubmed_fetch_fulltext`

`pubmed_format_citations`

`pubmed_find_related`

`pubmed_spell_check`

`pubmed_lookup_mesh`

Packages