PubMed MCP Server v2.0.0

A local Model Context Protocol (MCP) server that exposes the NCBI PubMed / PubMed Central / iCite APIs to MCP-compatible clients (Claude Desktop, MCP Inspector, etc.) over stdio.

This version (2.0.0) is a complete rewrite of the tool layer to provide feature parity with the remote OAuth-protected sibling project pubmed-mcp-remote-Oauth- — all 10 tools are identical in name, schema, and behavior. The local build simply drops OAuth and runs on stdio so it can be wired into Claude Desktop without authentication.

✨ What's new in v2.0.0

Breaking change: tool names and response shapes have changed. If you were using v1.x, update your client prompts to the new names.

Related MCP server: mcp-pubmed

🔧 Tools (10)

All tools return JSON in content[0].text.

For exact input/output schemas, run tools/list via MCP Inspector or check src/tools.ts.

📋 Prerequisites

• Node.js ≥ 18 (uses global fetch and AbortSignal.timeout)

• npm

• (optional) an NCBI API key — raises the rate limit from 3 req/s to 10 req/s

🔑 Getting an NCBI API key (optional but recommended)

Without a key, NCBI limits you to 3 requests/sec. With a free personal key, the limit goes up to 10 requests/sec — noticeable when running batch_process or large search paginations.

1. Create / sign in to an NCBI account: https://account.ncbi.nlm.nih.gov/

2. Open Account settings (top-right menu → Account settings) → scroll to API Key Management at the bottom of the page.

   • Direct link: https://account.ncbi.nlm.nih.gov/settings/ (look for "API Key Management")

3. Click Create an API Key. A 36-character hex string is generated immediately.

4. Copy that string and put it in the NCBI_API_KEY env var in your claude_desktop_config.json (see the Claude Desktop section below).

The key is tied to your NCBI account; revoke or rotate it any time from the same page. Don't commit it to git or share it — it's effectively your identity on the E-utilities API.

📚 Official policy: https://support.nlm.nih.gov/kbArticle/?pn=KA-05317

🚀 Installation

The server is published on npm as pubmed_mcp_server2. For Claude Desktop you don't need to install anything manually — npx -y pubmed_mcp_server2 will fetch and run it.

If you'd rather build from source (development):

git clone https://github.com/masa061580/pubmed_mcp_server2.git
cd pubmed_mcp_server2
npm install
npm run build      # produces dist/index.js

Smoke test (optional)

# From a clone:
( echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
  echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
  echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
  sleep 1
) | node dist/index.js

# Or directly from npm:
npx -y pubmed_mcp_server2

The server should list all 10 tools.

🖥️ Claude Desktop configuration

Edit (create if missing):

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

Recommended (via npm)

{
  "mcpServers": {
    "pubmed": {
      "command": "npx",
      "args": ["-y", "pubmed_mcp_server2"],
      "env": {
        "NCBI_API_KEY": ""
      }
    }
  }
}

Alternative (from a local clone)

{
  "mcpServers": {
    "pubmed": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/pubmed_mcp_server2/dist/index.js"
      ],
      "env": {
        "NCBI_API_KEY": ""
      }
    }
  }
}

Notes:

• Set NCBI_API_KEY to your key, or remove the env block entirely if you don't have one. With a key the rate limit goes from 3 req/s → 10 req/s.

• Windows users: if npx is not on PATH inside Claude Desktop, use the full path to npx.cmd (e.g. C:\\Program Files\\nodejs\\npx.cmd).

• macOS + nvm: if Claude Desktop can't find npx, replace "command": "npx" with the absolute path (e.g. /Users/you/.nvm/versions/node/v20.x.x/bin/npx). Claude Desktop's PATH may not include nvm shims.

• For the local-clone variant, use the absolute path to dist/index.js and run npm run build first.

• Fully quit and relaunch Claude Desktop after editing (Cmd+Q on macOS).

Logs

tail -f "$HOME/Library/Logs/Claude/mcp-server-pubmed.log"

🛠️ MCP Inspector

# Run the published package directly:
npx @modelcontextprotocol/inspector npx -y pubmed_mcp_server2

# Or inspect a local build:
npx @modelcontextprotocol/inspector node /ABSOLUTE/PATH/TO/dist/index.js

📦 Project structure

src/
├── index.ts          # stdio entry point — registers tools, connects transport
├── tools.ts          # 10 MCP tool definitions (zod schemas + handlers)
├── pubmed-client.ts  # NCBI E-utilities / iCite / ID-Converter client (XML parsing, 429 retry, timeouts)
└── ris-exporter.ts   # Minimal RIS format generator

The server is stateless — every request creates fresh state. Safe for concurrent invocations.

🤝 Sibling project

A remote, OAuth-protected variant deployed on Cloudflare Workers lives at: 👉 masa061580/pubmed-mcp-remote-Oauth-

Both servers expose the same 10 tools with identical schemas, so client prompts/workflows are portable between them.

📚 NCBI Compliance

This server respects NCBI E-utilities guidelines:

• Sends tool and email parameters on every request

• Honors rate limits (3 req/s without key, 10 req/s with key)

• Uses POST for large ID lists (efetch)

• Retries 429 with exponential backoff (max 3 attempts)

• 30s AbortSignal.timeout on every fetch

Please supply your own NCBI_API_KEY for production use and update email/tool in src/pubmed-client.ts to identify your deployment.

📝 License

MIT — see LICENSE.