NCBI Gene MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@NCBI Gene MCP Server search for BRCA1 gene in humans"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
NCBI Gene MCP Client
𧬠MCP client for fetching gene and protein metadata from NCBI Entrez API
This project provides a Model Context Protocol (MCP) client that interfaces with the NCBI Entrez API to fetch detailed information about genes and proteins. It's designed to be used both as a standalone command-line tool and as an MCP server for integration with MCP-compatible clients.
π Features
Gene Search: Search for genes using flexible queries
Gene Information: Fetch detailed gene metadata by NCBI Gene ID
Protein Information: Fetch protein details by NCBI Protein ID
Symbol Search: Search genes by symbol with optional organism filtering
Rate Limiting: Built-in respect for NCBI API rate limits
MCP Server: JSON-RPC server for MCP protocol integration
CLI Interface: Easy-to-use command-line interface
Related MCP server: genefoundry
π¦ Installation
From Source (Development)
# Clone the repository
git clone <repository-url>
cd ncbi_gene_mcp_client
# Install in development mode
pip install -e .From PyPI (when available)
pip install ncbi_gene_mcp_clientπ§ Usage
Command Line Interface
After installation, you can use the CLI commands:
Demo (Quick Start)
ncbi-gene-client demoSearch for genes
ncbi-gene-client search-genes "BRCA1"
ncbi-gene-client search-genes "breast cancer" --max-results 10Get gene information by ID
ncbi-gene-client gene-info 672 # BRCA1 geneSearch by gene symbol
ncbi-gene-client search-symbol BRCA1 --organism human
ncbi-gene-client search-symbol TP53Get protein information
ncbi-gene-client protein-info <protein_id>With NCBI credentials (recommended)
ncbi-gene-client --email your@email.com --api-key YOUR_API_KEY demoPython API
from ncbi_gene_mcp_client.main import NCBIGeneMCPClientBridge
# Initialize the client
client = NCBIGeneMCPClientBridge(
email="your@email.com", # Recommended by NCBI
api_key="your_api_key" # Optional, for higher rate limits
)
# Search for genes
results = client.search_genes("BRCA1[gene] AND human[organism]")
print(f"Found {results.count} genes")
# Get detailed gene information
gene_info = client.fetch_gene_info("672") # BRCA1
print(f"Gene: {gene_info.name}")
print(f"Description: {gene_info.description}")
print(f"Organism: {gene_info.organism}")
# Search by gene symbol
genes = client.search_by_gene_symbol("BRCA1", organism="human")
for gene in genes:
print(f"{gene.name}: {gene.description}")MCP Server
Run as an MCP server for integration with MCP-compatible clients:
ncbi-gene-mcp-serverThe MCP server provides the following tools:
search_genes: Search for genes using a query
fetch_gene_info: Get detailed gene information by ID
fetch_protein_info: Get protein information by ID
search_by_gene_symbol: Search genes by symbol with optional organism filter
π§ͺ Examples
Example 1: Basic Gene Search
from ncbi_gene_mcp_client.main import NCBIGeneMCPClientBridge
client = NCBIGeneMCPClientBridge()
# Search for BRCA1 gene
results = client.search_genes("BRCA1")
print(f"Found {results.count} results")
# Get details for the first result
if results.ids:
gene_info = client.fetch_gene_info(results.ids[0])
print(f"Gene: {gene_info.name}")
print(f"Chromosome: {gene_info.chromosome}")Example 2: Disease Gene Search
# Search for genes related to a disease
results = client.search_genes("diabetes[disease] AND human[organism]")
for gene_id in results.ids[:5]: # First 5 results
gene = client.fetch_gene_info(gene_id)
print(f"{gene.name}: {gene.description}")Example 3: Cross-species Gene Comparison
# Compare BRCA1 across species
for organism in ["human", "mouse", "rat"]:
genes = client.search_by_gene_symbol("BRCA1", organism=organism)
if genes:
gene = genes[0]
print(f"{organism}: {gene.name} on chromosome {gene.chromosome}")π Data Models
GeneInfo
{
"gene_id": "672",
"name": "BRCA1",
"description": "BRCA1 DNA repair associated",
"organism": "Homo sapiens",
"chromosome": "17",
"map_location": "17q21.31",
"gene_type": "protein-coding",
"other_aliases": ["BRCAI", "BRCC1", "BROVCA1"],
"summary": "This gene encodes a 190 kD nuclear phosphoprotein..."
}SearchResult
{
"count": 1,
"ids": ["672"],
"query_translation": "BRCA1[gene]"
}βοΈ Configuration
NCBI API Guidelines
It's recommended to provide your email address when using the NCBI API:
client = NCBIGeneMCPClientBridge(email="your@email.com")For higher rate limits, you can also provide an API key:
client = NCBIGeneMCPClientBridge(
email="your@email.com",
api_key="your_ncbi_api_key"
)Rate Limiting
The client automatically handles NCBI's rate limiting requirements:
Without API key: 3 requests per second
With API key: 10 requests per second
π§ͺ Testing
Run the test suite:
# Install test dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run with coverage
pytest --cov=ncbi_gene_mcp_client
# Run integration tests (requires internet)
pytest -m integrationπ Development
Setting up for development
# Clone and install in development mode
git clone <repository-url>
cd ncbi_gene_mcp_client
pip install -e ".[dev]"
# Run linting
flake8 ncbi_gene_mcp_client/
mypy ncbi_gene_mcp_client/
# Format code
black ncbi_gene_mcp_client/Project Structure
ncbi_gene_mcp_client/
βββ ncbi_gene_mcp_client/
β βββ __init__.py
β βββ main.py # Main client class
β βββ bridge.py # NCBI API bridge
β βββ models.py # Data models
β βββ mcp_server.py # MCP server implementation
β βββ cli.py # Command-line interface
βββ tests/
β βββ __init__.py
β βββ test_main.py # Test suite
βββ pyproject.toml # Project configuration
βββ README.md # This file
βββ LICENSE # MIT Licenseπ NCBI Resources
π License
This project is licensed under the MIT License - see the LICENSE file for details.
π¨βπ» Author
Mohammad Najeeb
π§ mona00002@uni-saarland.de
π€ Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Features
Feature 1: Description of feature 1
Feature 2: Description of feature 2
Feature 3: Description of feature 3
MCP Integration: Full Model Context Protocol server implementation
API Methods
Core Methods
method1(): Description of method1method2(): Description of method2method3(): Description of method3
Configuration
The package uses a configuration class for settings:
from ncbi_gene_mcp_client.main import NCBIGeneMCPClientConfig, NCBIGeneMCPClientBridge
config = NCBIGeneMCPClientConfig(
base_url="https://api.example.com",
api_key="your_api_key",
timeout=30.0
)
bridge = NCBIGeneMCPClientBridge(config)MCP Server Configuration
To use the MCP server with an MCP client, configure it as follows:
{
"mcpServers": {
"ncbi_gene_mcp_client": {
"command": "ncbi_gene_mcp_client-server",
"env": {}
}
}
}The server will automatically handle:
JSON-RPC communication
Tool discovery and invocation
Error handling and reporting
Development
Setup Development Environment
# Install in development mode with dev dependencies
pip install -e .[dev]
# Run tests
pytest
# Format code
black ncbi_gene_mcp_client/
# Type checking
mypy ncbi_gene_mcp_client/Project Structure
ncbi_gene_mcp_client/
βββ pyproject.toml # Package configuration
βββ README.md # This file
βββ LICENSE # MIT License
βββ ncbi_gene_mcp_client/ # Main package
β βββ __init__.py # Package initialization
β βββ main.py # Core functionality
β βββ mcp_server.py # MCP server implementation
βββ tests/ # Test files
βββ __init__.py
βββ test_main.py # Tests for main functionalityLicense
MIT License - see LICENSE file for details.
Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests
Run the test suite
Submit a pull request
Support
For issues and questions, please use the GitHub issue tracker.
Available Tools
4 toolsfetch_gene_infoC
Fetch detailed information for a specific gene ID
Inputs: gene_id (required).
fetch_protein_infoC
Fetch detailed information for a specific protein ID
Inputs: protein_id (required).
search_by_gene_symbolC
Search for genes by symbol with optional organism filter
Inputs: symbol (required), organism.
search_genesC
Search for genes in NCBI database using a query
Inputs: query (required), max_results.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 4 tools
The tools have some overlap that could cause confusion, particularly between 'search_by_gene_symbol' and 'search_genes' which both search for genes but with different parameters. However, 'fetch_gene_info' and 'fetch_protein_info' are clearly distinct from each other and from the search tools, providing some clarity.
The naming follows a consistent snake_case pattern with clear verb_noun structure (e.g., fetch_gene_info, search_genes). The only minor deviation is 'search_by_gene_symbol' which includes a preposition, but it still maintains readability and overall consistency with the other tools.
With 4 tools, the count is borderline thin for a gene database server, as it might lack operations like updating or deleting data, but it covers basic fetch and search functionalities. It's reasonable for a focused scope but could benefit from more comprehensive coverage.
The server provides fetch and search operations for genes and proteins, but there are notable gaps such as no update, delete, or creation tools, which might be expected in a full CRUD lifecycle. It covers basic retrieval and search, but agents may hit dead ends for more complex tasks.
Maintenance
Related MCP Connectors
MyGene.info MCP. Docs: https://docs.mygene.info/en/latest/
NCBI E-utilities MCP β federated Entrez search/fetch.
Auditable MCP server for PubMed, Europe PMC, ClinicalTrials.gov, and bioRxiv/medRxiv queries
MCP gateway federating 22 biomedical MCP servers behind one endpoint: gnomAD, ClinVar, HPO, VEP.
Related MCP Servers
- AlicenseAqualityBmaintenanceA high-performance MCP server that gives LLMs access to 25 biomedical tools federated across 50+ upstream APIs for genes, variants, drugs, diseases, literature, clinical trials, and structural biology.43155 npm12Apache 2.0
- AlicenseNot gradedqualityBmaintenanceFederates 13 gene-related MCP backends (gnomAD, GTEx, etc.) behind a single Streamable HTTP endpoint with collision-free namespacing and search-based tool discovery.7MIT
- AlicenseAqualityDmaintenanceMCP server that exposes the UniProt REST API to LLM clients, enabling search and retrieval of protein data via tools like search_uniprotkb, get_entry, and map_ids.7MIT
- FlicenseAqualityDmaintenanceMCP server for accessing NCBI PubMed/PMC databases, enabling search, retrieval of summaries and full records, citation export, and ID conversion through various APIs.121-