Ncbi Gene MCP Client

🚀 NCBI Gene MCP Client

🧬 An MCP client designed to retrieve gene and protein metadata from the NCBI Entrez API

This project offers a Model Context Protocol (MCP) client that connects with the NCBI Entrez API. It can fetch comprehensive information about genes and proteins. You can use it either as a standalone command - line tool or as an MCP server for seamless integration with MCP - compatible clients.

✨ Features

• Gene Search: Conduct flexible queries to search for genes.
• Gene Information: Retrieve detailed gene metadata using the NCBI Gene ID.
• Protein Information: Obtain protein details via the NCBI Protein ID.
• Symbol Search: Search for genes by symbol, with the option to filter by organism.
• Rate Limiting: Automatically adheres to the NCBI API rate limits.
• MCP Server: A JSON - RPC server for MCP protocol integration.
• CLI Interface: An 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 Examples

Command Line Interface

After installation, you can utilize the following 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 it as an MCP server for integration with MCP - compatible clients:

ncbi-gene-mcp-server

The MCP server offers the following tools:

• search_genes: Search for genes using a query.
• fetch_gene_info: Retrieve detailed gene information by ID.
• fetch_protein_info: Get protein information by ID.
• search_by_gene_symbol: Search genes by symbol, with an optional organism filter.

Basic Usage

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}")

Advanced Usage

# 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}")

# 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}")

📚 Documentation

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 is 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 manages NCBI's rate limiting requirements:

• Without API key: 3 requests per second.
• With API key: 10 requests per second.

🔧 Technical Details

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

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.

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

This project is licensed under the MIT License. See the LICENSE file for detailed information.

👨‍💻 Author

Mohammad Najeeb
📧 mona00002@uni-saarland.de

🤝 Contributing

Contributions are highly welcome! Please feel free to submit a Pull Request.

💡 Usage Tip

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