PubMed MCP Server - Remote Edition

A comprehensive Model Context Protocol (MCP) server for PubMed database access, optimized for deployment on render.com and other cloud platforms. This server provides advanced biomedical literature search, retrieval, and analysis capabilities through both local (stdio) and remote (SSE/HTTP) transports.

🚀 Features

🔧 Tools

• search_pubmed: Search PubMed with comprehensive summaries and metadata
• get_full_abstract: Retrieve complete abstracts by PMID
• get_full_text: Extract full text from PMC open access articles
• export_ris: Export citations in RIS format for reference managers
• get_citation_counts: Analyze citation metrics using NCBI elink API
• optimize_search_query: Transform natural language to optimized PubMed queries with MeSH terms
• find_similar_articles: Find similar articles using NCBI's similarity algorithm
• batch_process: Process multiple PMIDs with multiple operations efficiently

🌐 Deployment Modes

• Local Mode: Traditional stdio transport for Claude Desktop
• Remote Mode: SSE/HTTP transport for cloud deployment (render.com, etc.)

📋 Prerequisites

• Node.js v18.x or higher
• npm or yarn package manager
• (Optional) render.com account for cloud deployment

🎯 Installation & Usage

Option 1: Deploy to Render.com (Recommended for Remote Access)

1. Fork or clone this repository

2. Connect to Render.com

   • Sign up at render.com
   • Click "New +" → "Web Service"
   • Connect your GitHub repository

3. Configure Environment Variables in Render dashboard:

   NODE_ENV=production
   MCP_TRANSPORT=sse
   PORT=8000
   HOST=0.0.0.0
   LOG_LEVEL=info
   NCBI_EMAIL=your-email@example.com
   

4. Deploy

   • Render will automatically detect render.yaml and deploy
   • Your service URL will be: https://pubmed-mcp-server.onrender.com

5. Add to Claude Desktop

Add to your Claude Desktop configuration:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pubmed-remote": {
      "url": "https://your-service-name.onrender.com/sse"
    }
  }
}

Option 2: Local Installation

1. Clone and install

git clone <repository-url>
cd pubmed-mcp-remote
npm install
npm run build

2. Configure for Local Mode

Add to Claude Desktop configuration:

{
  "mcpServers": {
    "pubmed": {
      "command": "node",
      "args": ["/path/to/pubmed-mcp-remote/dist/index.js"],
      "env": {
        "NCBI_EMAIL": "your-email@example.com"
      }
    }
  }
}

Option 3: Development Mode

# Local stdio mode
npm run dev

# Remote SSE mode
MCP_TRANSPORT=sse npm run dev

⚙️ Configuration

Environment Variables

Variable	Description	Default	Required
NODE_ENV	Environment mode	development	No
MCP_TRANSPORT	Transport mode (sse or stdio)	stdio	No
PORT	Server port (remote mode only)	8000	No
HOST	Server host (remote mode only)	0.0.0.0	No
LOG_LEVEL	Logging level (debug, info, warn, error)	info	No
NCBI_EMAIL	Email for NCBI API (required by NCBI)	user@example.com	Yes
MAX_RESULTS	Maximum search results	100	No
REQUEST_TIMEOUT	API timeout in milliseconds	30000	No

Transport Modes

Stdio Mode (Local)

• Traditional MCP transport for local Claude Desktop
• Activated by default or when MCP_TRANSPORT=stdio
• Communication via stdin/stdout

SSE Mode (Remote)

• HTTP/SSE transport for remote deployment
• Activated when MCP_TRANSPORT=sse or --remote flag
• Provides HTTP endpoints:
  • /sse - SSE connection endpoint
  • /health - Health check endpoint
  • /message - Client-to-server messaging

🔍 Example Usage

1. Query Optimization

Input: "covid vaccine effectiveness in elderly"
→ Output: Optimized PubMed query with MeSH terms

2. Literature Search

Tool: search_pubmed
Query: "diabetes treatment 2023"
Max Results: 10
→ Returns: Detailed articles with abstracts and metadata

3. Citation Analysis

Tool: get_citation_counts
PMIDs: ["36038128", "30105375"]
→ Returns: Citation counts and citing articles

4. Batch Processing

Tool: batch_process
PMIDs: ["36038128", "35105375", "34567890"]
Operations: ["abstract", "citations", "similar"]
→ Returns: Comprehensive analysis of all articles

📊 API Limits

Operation	Limit	Notes
Search results	100 articles	Per query
Full abstracts	20 PMIDs	Per request
Full text	10 PMC articles	Per request
Citation analysis	20 PMIDs	Per request
RIS export	50 PMIDs	Per batch
Similar articles	50 articles	Per PMID (default: 10)
Batch processing	50 PMIDs	Per batch, 5 concurrent ops
API delays	200-600ms	Between requests

🛡️ Rate Limiting & Best Practices

1. NCBI Guidelines Compliance

   • Always provide a valid email address in NCBI_EMAIL
   • Respect API rate limits (3 requests/second without API key)
   • Use delays between requests (automatically handled)

2. Error Handling

   • Network connectivity issues
   • Invalid PMIDs or queries
   • API timeouts
   • Missing full text content

3. Performance Optimization

   • Use batch processing for multiple articles
   • Cache results when possible
   • Use query optimization for better search results

🏗️ Project Structure

pubmed-mcp-remote/
├── src/
│   ├── index.ts           # Main server with dual transport support
│   └── pubmed-api.ts      # PubMed API integration
├── dist/                  # Compiled JavaScript output
├── render.yaml            # Render.com deployment config
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
├── .gitignore            # Git ignore rules
└── README.md             # This file

🔧 Development

Build

npm run build

Run Locally (stdio)

npm start

Run as Remote Server (SSE)

npm run start:remote
# or
MCP_TRANSPORT=sse npm start

Clean Build

npm run clean

🚀 Deployment

Render.com

The repository includes a render.yaml file for automatic deployment:

1. Push your code to GitHub
2. Connect repository to Render
3. Render automatically deploys using render.yaml
4. Update environment variables in Render dashboard

Other Platforms

For deployment to other platforms (Heroku, AWS, DigitalOcean, etc.):

1. Set MCP_TRANSPORT=sse environment variable
2. Set PORT to platform-required value
3. Run npm run build && npm run start:remote

📖 MeSH Term Optimization

The server includes extensive medical term mappings:

• COVID-19 & Vaccines: covid, coronavirus, vaccination
• Cardiovascular: heart attack, myocardial infarction
• Cancer: tumor, oncology, carcinoma
• Mental Health: depression, anxiety
• Study Types: clinical trial, meta-analysis, RCT
• Treatment Types: therapy, surgery, medication

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly (both local and remote modes)
5. Submit a pull request

📝 Version History

v1.0.2 (Current)

• ✨ Added remote/SSE transport support
• 🌐 Render.com deployment configuration
• 🔧 Environment variable configuration
• 📊 Health check endpoint
• ⚡ Dual mode support (stdio/SSE)

v1.0.1

• 🆕 Similar articles feature
• 📊 Citation analysis improvements

v1.0.0

• 🚀 Initial release
• 📖 Core PubMed functionality

📄 License

MIT License - see LICENSE file for details

🙋‍♂️ Support

For issues or questions:

1. Check existing GitHub issues
2. Create a new issue with detailed description
3. Include error messages and reproduction steps

🔗 Related Resources

• NCBI E-utilities Documentation
• PubMed Search Tips
• Model Context Protocol
• Render.com Docs
• Claude Desktop

🎯 Quick Start Checklist

• [ ] Clone repository
• [ ] Install dependencies (npm install)
• [ ] Build project (npm run build)
• [ ] Set NCBI_EMAIL environment variable
• [ ] Choose deployment mode (local or remote)
• [ ] Configure Claude Desktop
• [ ] Test with a simple search query

⚡ Performance Tips

1. Use query optimization for better search results
2. Batch process when analyzing multiple articles
3. Cache results to avoid redundant API calls
4. Monitor rate limits to prevent API throttling
5. Use specific PMIDs when possible for faster retrieval