A Model Context Protocol (MCP) server for searching NCBI databases, designed for researchers across all life sciences and biomedical fields. This server provides seamless access to PubMed's vast collection of 35+ million scientific articles through natural language queries, enabling AI assistants to help with literature reviews, research discovery, and scientific analysis. 🔬 Comprehensive Search:
Add this skill
npx mdskills install vitorpavinato/ncbi-mcp-serverWell-documented MCP server with comprehensive PubMed search tools and excellent setup guidance
1# NCBI Literature Search MCP Server23A Model Context Protocol (MCP) server for searching NCBI databases, designed for researchers across all life sciences and biomedical fields. This server provides seamless access to PubMed's vast collection of 35+ million scientific articles through natural language queries, enabling AI assistants to help with literature reviews, research discovery, and scientific analysis.45## Features67🔬 **Comprehensive Search**: Search PubMed's 35+ million articles across all biological disciplines8📊 **Advanced Queries**: Support for complex searches with boolean operators, field tags, and filters9🧬 **Life Sciences Research**: Covers all biological and biomedical fields including genetics, ecology, medicine, and biotechnology10💻 **Computational Biology**: Perfect for finding bioinformatics methods, algorithms, and computational tools11🔬 **Research Applications**: Literature reviews, hypothesis generation, method discovery, and staying current with scientific advances12📚 **Full Article Details**: Get abstracts, author lists, MeSH terms, DOIs, and publication information13🔗 **Related Articles**: Discover relevant research through NCBI's relationship algorithms14📖 **MeSH Integration**: Search and utilize Medical Subject Headings for precise terminology1516## Quick Start1718### Prerequisites19- Python 3.8 or higher20- Poetry (recommended) - [Install Poetry](https://python-poetry.org/docs/#installation)2122### Setup (5 minutes)23241. **Create and initialize project**25 ```bash26 mkdir ncbi-mcp-server && cd ncbi-mcp-server27 poetry init28 ```29 During init, add dependencies: `mcp`, `httpx`, `typing-extensions`30312. **Create project structure**32 ```bash33 mkdir -p src/ncbi_mcp_server34 # Save server.py code as src/ncbi_mcp_server/server.py35 ```36373. **Install dependencies**38 ```bash39 poetry install40 ```41424. **Test the server**43 ```bash44 poetry run python src/ncbi_mcp_server/server.py45 ```46475. **Configure Claude Desktop**4849 Edit your Claude Desktop config file:50 - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`51 - **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`52 - **Linux**: `~/.config/claude/claude_desktop_config.json`5354 Add this configuration:55 ```json56 {57 "mcpServers": {58 "ncbi-literature": {59 "command": "poetry",60 "args": ["run", "python", "src/ncbi_mcp_server/server.py"],61 "cwd": "/FULL/PATH/TO/YOUR/ncbi-mcp-server"62 }63 }64 }65 ```66676. **Restart Claude Desktop** and start searching!6869### Alternative Setup Methods7071<details>72<summary>Click to expand alternative installation methods</summary>7374#### **Conda Environment**75```bash76conda env create -f environment.yml77conda activate ncbi-mcp78python server.py79```8081#### **Standard pip + venv**82```bash83python -m venv venv84source venv/bin/activate # Linux/macOS85pip install -r requirements.txt86python server.py87```88</details>8990## Usage Examples9192### For Evolutionary Biology Research9394**Search for phylogenetic studies:**95```96"Search for recent phylogenetic analysis papers on mammalian evolution"97→ Uses: search_pubmed with query "phylogenetic analysis[ti] AND mammalian[ti] AND evolution"98```99100**Find computational phylogenetics methods:**101```102"Find papers about maximum likelihood methods for phylogenetic reconstruction"103→ Uses: search_pubmed with query "maximum likelihood[ti] AND phylogenetic reconstruction"104```105106**Search by specific organism:**107```108"Find recent papers on Drosophila comparative genomics"109→ Uses: search_pubmed with query "Drosophila[ti] AND comparative genomics[ti]"110```111112### For Computational Biology Research113114**Algorithm and method papers:**115```116"Search for machine learning applications in genomics from the last 2 years"117→ Uses: search_pubmed with date_range="730" and query "machine learning AND genomics"118```119120**Software and database papers:**121```122"Find papers about new bioinformatics tools for sequence analysis"123→ Uses: search_pubmed with query "bioinformatics[ti] AND software[ti] AND sequence analysis"124```125126### Advanced Search Examples127128**Multi-criteria search:**129```130"Find review articles about CRISPR applications in evolutionary studies published in Nature or Science"131→ Uses: advanced_search with terms=["CRISPR", "evolution"], publication_types=["Review"], journals=["Nature", "Science"]132```133134**Author-specific searches:**135```136"Find recent papers by researchers working on ancient DNA and phylogenomics"137→ Uses: search_pubmed with query "ancient DNA[ti] AND phylogenomics[ti]"138```139140## Tool Reference141142### `search_pubmed`143Primary search tool for PubMed database144- **query**: Search terms (supports field tags like `[ti]` for title, `[au]` for author, `[mh]` for MeSH terms)145- **max_results**: Number of results (1-100, default: 20)146- **sort**: Sort by "relevance", "pub_date", "author", or "journal"147- **date_range**: Limit to recent articles ("30", "90", "365", "1095" days)148149**Examples:**150- `"CRISPR[ti] AND evolution"` - CRISPR in title AND evolution anywhere151- `"phylogenetic analysis[mh]"` - Using MeSH term for phylogenetic analysis152- `"computational biology AND machine learning"` - Boolean search153154### `get_article_details`155Fetch complete information for specific articles156- **pmids**: List of PubMed IDs (up to 50)157158Returns full abstracts, author lists, MeSH terms, DOI, publication details159160### `search_mesh_terms`161Find standardized Medical Subject Headings162- **term**: Term to search in MeSH database163164Helps discover related concepts and improve search precision165166### `get_related_articles`167Discover articles related to a specific paper168- **pmid**: PubMed ID of reference article169- **max_results**: Number of related articles (1-50, default: 10)170171Perfect for literature reviews and finding relevant research172173### `advanced_search`174Complex searches with multiple criteria175- **terms**: List of search terms to combine176- **operator**: "AND", "OR", or "NOT" to combine terms177- **authors**: List of author names178- **journals**: List of journal names179- **publication_types**: "Research Article", "Review", "Meta-Analysis", etc.180- **date_from/date_to**: Date range in YYYY/MM/DD format181- **max_results**: Number of results (1-100, default: 20)182183## Analytics & Performance Monitoring184185The NCBI MCP Server includes comprehensive analytics to help you understand your research patterns and optimize performance.186187### Analytics Tools188189#### `get_analytics_summary`190Get comprehensive analytics overview191```192"Show me my research analytics summary"193```194Returns:195- Total requests and uptime196- Operation breakdown (searches, fetches, etc.)197- Cache performance metrics198- Recent activity and error rates199- System health indicators200201#### `get_detailed_metrics`202Detailed performance metrics for specific time periods203```204"Get detailed metrics for the last 24 hours"205```206- **hours**: Time period to analyze (default: 24)207- Operation-specific performance data208- Timeline analysis with hourly breakdowns209- Error rates and response times per operation210211#### `reset_analytics`212Reset analytics data (use with caution)213```214"Reset all analytics data"215```216**Note**: This permanently clears all collected metrics.217218### What's Tracked219220**Usage Patterns:**221- Search queries and frequency222- Most used operations223- Unique vs. repeated queries224- Peak usage periods225226**Performance Metrics:**227- Response times for each operation228- Cache hit/miss rates229- Error rates and types230- Rate limiting efficiency231232**Research Insights:**233- Popular search terms and patterns234- Research workflow analysis235- Literature access patterns236- Most accessed journals and topics237238## Deployment239240### Quick Start2412421. **Configure credentials:**243 ```bash244 cp .env.example .env245 # Edit .env with your NCBI email and API key246 ```2472482. **Choose deployment method:**249 ```bash250 # Local development251 ./deploy.sh local252253 # Docker deployment254 ./deploy.sh docker255256 # Production deployment257 ./deploy.sh production258 ```259260### Deployment Options261262#### 1. Local Development263Perfect for development and testing:264```bash265poetry install266poetry run python -m src.ncbi_mcp_server.server267```268269#### 2. Docker Deployment270Recommended for most users with two options:271272**Full setup with Redis (recommended):**273```bash274# Copy and configure environment275cp .env.example .env276# Edit .env with your NCBI email and API key277278# Start all services279docker-compose up -d280```281282**Simple setup without Redis:**283```bash284# For basic usage without Redis dependencies285cp .env.example .env286# Edit .env with your NCBI email287288docker-compose -f docker-compose.simple.yml up -d289```290291**Full setup includes:**292- NCBI MCP Server container293- Redis cache for performance294- Redis Commander UI (http://localhost:8081)295296**Simple setup includes:**297- NCBI MCP Server container only298- In-memory caching (no persistence)299300#### 3. Production Deployment301For production environments:302```bash303# Configure production settings304cp .env.production .env305# Edit with production values306307# Deploy308./deploy.sh production309```310311### Monitoring312313**Docker logs:**314```bash315docker-compose logs -f ncbi-mcp-server316```317318**Cache monitoring:**319- Redis Commander: http://localhost:8081320- Cache stats via MCP tool: `cache_stats()`321322**Health checks:**323```bash324# Test server health325curl http://localhost:8000/health326327# Test via MCP328python -c "from src.ncbi_mcp_server.server import cache_stats; import asyncio; print(asyncio.run(cache_stats()))"329```330331## Configuration332333### NCBI API Key (Optional but Recommended)334For higher rate limits and better performance:3353361. **Register at NCBI**: https://www.ncbi.nlm.nih.gov/account/3372. **Get API key**: https://www.ncbi.nlm.nih.gov/account/settings/3383. **Add to server code** in `src/ncbi_mcp_server/server.py`:339340```python341# Replace the line: ncbi_client = NCBIClient()342# With:343ncbi_client = NCBIClient(344 email="your.email@university.edu",345 api_key="your_api_key_here"346)347```348349### Rate Limits350- **Without API key**: 3 requests/second351- **With API key**: 10 requests/second352- **With API key + email**: Higher limits for bulk requests353354## Development Workflow355356### Poetry Commands357```bash358poetry shell # Activate virtual environment359poetry add package # Add new dependency360poetry remove package # Remove dependency361poetry update # Update all dependencies362poetry run python ... # Run commands in environment363poetry build # Create distribution packages364```365366### Code Quality (if you added dev dependencies)367```bash368poetry add --group dev black mypy pytest isort flake8369poetry run black . # Format code370poetry run mypy . # Type checking371poetry run pytest # Run tests372poetry run isort . # Sort imports373```374375### Sharing with Colleagues376```bash377# They just need:378git clone your-repo379cd ncbi-mcp-server380poetry install381# Everything works identically!382```383384## Field Tags for Advanced Searches385386PubMed supports many field tags for precise searching:387388- `[ti]` - Title389- `[tiab]` - Title and Abstract390- `[au]` - Author391- `[mh]` - MeSH Terms392- `[journal]` - Journal Name393- `[pdat]` - Publication Date394- `[pt]` - Publication Type395- `[lang]` - Language396- `[sb]` - Subset (e.g., medline, pubmed)397398**Example Advanced Queries:**399```400"machine learning"[ti] AND "phylogen*"[tiab] AND "2020"[pdat]:"2024"[pdat]401evolutionary[mh] AND computational[ti] AND (genomics[tiab] OR proteomics[tiab])402"ancient DNA"[ti] AND (paleogenomics[mh] OR phylogenomics[tiab])403```404405## Research Workflow Examples406407### Literature Review Workflow4081. **Start broad**: `search_pubmed("computational phylogenetics")`4092. **Refine with MeSH**: `search_mesh_terms("phylogenetics")`4103. **Find key papers**: Use publication dates and journal filters4114. **Explore connections**: `get_related_articles(pmid="key_paper_id")`4125. **Deep dive**: `get_article_details(pmids=["12345", "67890"])`413414### Staying Current4151. **Recent methods**: `search_pubmed("new methods", date_range="90")`4162. **Follow key authors**: `search_pubmed("author_name[au]", sort="pub_date")`4173. **Track specific topics**: `advanced_search` with your research keywords418419### Method Discovery4201. **Algorithm papers**: `search_pubmed("algorithm[ti] AND your_field")`4212. **Software tools**: `search_pubmed("software[ti] OR tool[ti] AND bioinformatics")`4223. **Benchmarking**: `search_pubmed("comparison[ti] OR benchmark[ti]")`423424## Troubleshooting425426### Common Issues427428**Server won't start:**429- Check Python version (3.8+ required)430- Install dependencies: `pip install -r requirements.txt`431- Verify file permissions432433**No search results:**434- Check query syntax (use proper field tags)435- Try broader search terms436- Verify internet connection437438**Rate limit errors:**439- Add delays between requests440- Get NCBI API key for higher limits441- Consider searching fewer results per query442443**XML parsing errors:**444- Usually temporary NCBI server issues445- Retry after a few seconds446- Check NCBI status: https://www.ncbi.nlm.nih.gov/447448### Getting Help449450- **NCBI E-utilities documentation**: https://www.ncbi.nlm.nih.gov/books/NBK25499/451- **PubMed search tips**: https://pubmed.ncbi.nlm.nih.gov/help/452- **MeSH database**: https://www.ncbi.nlm.nih.gov/mesh/453454## Contributing455456This MCP server is designed to grow with the research community. Ideas for enhancement:457458- **Additional databases**: PMC, BioRxiv, databases beyond NCBI459- **Citation analysis**: Track paper impact and citation networks460- **Export formats**: BibTeX, EndNote, RIS for reference managers461- **Saved searches**: Persistent search profiles and alerts462- **Full-text integration**: When available through PMC463464## License465466This project is open source. Feel free to modify and distribute according to your institution's policies.467468---469470**Perfect for researchers in:**471- Evolutionary Biology & Phylogenetics472- Computational Biology & Bioinformatics473- Molecular Evolution & Population Genetics474- Comparative Genomics & Proteomics475- Systems Biology & Network Analysis476- Biostatistics & Mathematical Biology477- Ancient DNA & Paleogenomics478- Conservation Genetics & Ecology479480Start exploring the vast world of biological literature with powerful, precise searches!
Full transparency — inspect the skill content before installing.