Click on "Install 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 Serversearch 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: SerpApi MCP Server
📦 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.