Skip to main content
Glama
NCBI Gene MCP Server

NCBI Gene MCP Server

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

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

Available Tools

4 tools
fetch_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

    B3/5.0

    Scored across 4 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      43
      155 npm
      12
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Federates 13 gene-related MCP backends (gnomAD, GTEx, etc.) behind a single Streamable HTTP endpoint with collision-free namespacing and search-based tool discovery.
      7
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      7
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      MCP server for accessing NCBI PubMed/PMC databases, enabling search, retrieval of summaries and full records, citation export, and ID conversion through various APIs.
      12
      1
      -