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

📦 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 demo

Search for genes

ncbi-gene-client search-genes "BRCA1"
ncbi-gene-client search-genes "breast cancer" --max-results 10

Get gene information by ID

ncbi-gene-client gene-info 672  # BRCA1 gene

Search by gene symbol

ncbi-gene-client search-symbol BRCA1 --organism human
ncbi-gene-client search-symbol TP53

Get 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 demo

Python 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-server

The 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

• NCBI Entrez Programming Utilities
• NCBI Gene Database
• E-utilities API Documentation

📄 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 method1
• method2(): Description of method2
• method3(): 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 functionality

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request

Support

For issues and questions, please use the GitHub issue tracker.