io.github.cyanheads/pubmed-mcp-server
Comprehensive PubMed MCP Server to search, retrieve, and analyze biomedical literature from NCBI.
Ask AI about io.github.cyanheads/pubmed-mcp-server
Powered by Claude Β· Grounded in docs
I know everything about io.github.cyanheads/pubmed-mcp-server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
@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.
Public Hosted Server: https://pubmed.caseyjhand.com/mcp
Tools
Nine 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_lookup_citation | Resolve partial bibliographic references to PubMed IDs via ECitMatch |
pubmed_convert_ids | Convert between DOI, PMID, and PMCID using the PMC ID Converter API |
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
- Returns the original query plus the fully applied PubMed query and normalized filter metadata
pubmed_fetch_articles
Fetch full article metadata by PubMed IDs.
- Batch fetch up to 200 articles at once (auto-switches to POST for batches >= 100)
- 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
- Reports formatted counts and unavailable PMIDs for partial-result handling
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
similarrelationship 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
pubmed_lookup_citation
Resolve partial bibliographic references to PubMed IDs via NCBI ECitMatch.
- Match citations by journal, year, volume, first page, and/or author name
- More fields = better match accuracy; at least one field required
- Batch up to 25 citations per request
- Deterministic matching β more reliable than free-text search for known references
- Returns explicit
matched,not_found, andambiguousstatuses with recovery detail
pubmed_convert_ids
Convert between article identifiers (DOI, PMID, PMCID) using the PMC ID Converter API.
- Batch up to 50 IDs per request
- Accepts DOIs, PMIDs, or PMCIDs (all IDs must be the same type)
- Only resolves articles indexed in PubMed Central
- Returns all available identifier mappings for each input ID
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, ECitMatch) plus PMC ID Converter
- Sequential request queue with configurable delay for NCBI rate limit compliance
- NCBI-specific XML parser with
isArrayhints 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_HTTP_ENDPOINT_PATH | HTTP endpoint path where the MCP server is mounted | /mcp |
MCP_PUBLIC_URL | Public origin override for TLS-terminating reverse-proxy deployments (landing page, Server Card, RFC 9728 metadata). | none |
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 | 6 |
NCBI_TIMEOUT_MS | Per-request HTTP timeout in ms | 30000 |
NCBI_TOTAL_DEADLINE_MS | Total deadline across all retry attempts for one NCBI call, in ms | 60000 |
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). Nine 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/catchin tool logic - Use
ctx.logfor logging,ctx.statefor 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.
