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.
🧬 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.
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
# Clone the repository
git clone <repository-url>
cd ncbi_gene_mcp_client
# Install in development mode
pip install -e .pip install ncbi_gene_mcp_clientAfter installation, you can use the CLI commands:
ncbi-gene-client demoncbi-gene-client search-genes "BRCA1"
ncbi-gene-client search-genes "breast cancer" --max-results 10ncbi-gene-client gene-info 672 # BRCA1 genencbi-gene-client search-symbol BRCA1 --organism human
ncbi-gene-client search-symbol TP53ncbi-gene-client protein-info <protein_id>ncbi-gene-client --email your@email.com --api-key YOUR_API_KEY demofrom 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}")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
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}")# 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}"){
"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..."
}{
"count": 1,
"ids": ["672"],
"query_translation": "BRCA1[gene]"
}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"
)The client automatically handles NCBI's rate limiting requirements:
Without API key: 3 requests per second
With API key: 10 requests per second
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# 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/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 LicenseThis project is licensed under the MIT License - see the LICENSE file for details.
Mohammad Najeeb
📧 mona00002@uni-saarland.de
Contributions are welcome! Please feel free to submit a Pull Request.
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
method1(): Description of method1
method2(): Description of method2
method3(): Description of method3
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)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
# 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/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 functionalityMIT License - see LICENSE file for details.
Fork the repository
Create a feature branch
Make your changes
Add tests
Run the test suite
Submit a pull request
For issues and questions, please use the GitHub issue tracker.
Fetch detailed information for a specific gene ID
| Name | Required | Description | Default |
|---|---|---|---|
| gene_id | Yes | NCBI Gene ID (e.g., '672' for BRCA1) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool fetches 'detailed information' but doesn't specify what that includes (e.g., gene function, location, aliases), whether it's a read-only operation, potential rate limits, or error handling. This leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It front-loads the key action and resource, making it easy to parse quickly, which is ideal for conciseness in tool descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what 'detailed information' entails, how results are structured, or any behavioral traits like safety or performance. For a tool with no structured context, this leaves the agent under-informed about its operation and outputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'gene_id' fully documented in the schema as an NCBI Gene ID with an example. The description adds no additional parameter semantics beyond what the schema provides, so it meets the baseline for high schema coverage without compensating value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('fetch') and resource ('detailed information for a specific gene ID'), making the purpose immediately understandable. However, it doesn't differentiate this tool from its siblings like 'fetch_protein_info' or 'search_by_gene_symbol', which likely retrieve related but distinct information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'search_by_gene_symbol' or 'search_genes'. It mentions fetching by 'gene ID' but doesn't clarify if this is preferred over other identifiers or search methods, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch detailed information for a specific protein ID
| Name | Required | Description | Default |
|---|---|---|---|
| protein_id | Yes | NCBI Protein ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool fetches information, implying a read-only operation, but doesn't address key aspects like authentication needs, rate limits, error handling, or what 'detailed information' entails in the response. This leaves significant gaps for agent understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized for a simple tool, though it could be slightly more informative to enhance clarity without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema, no annotations), the description is minimal. It lacks context on what 'detailed information' includes, how results are structured, or any behavioral traits like data source or limitations, making it incomplete for reliable agent use despite the straightforward schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'protein_id' documented as 'NCBI Protein ID'. The description adds no additional parameter details beyond what the schema provides, such as format examples or constraints, so it meets the baseline for high schema coverage without compensating value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('fetch detailed information') and target resource ('for a specific protein ID'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'fetch_gene_info' or 'search_by_gene_symbol', which likely retrieve related but different biological data, so it misses full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'fetch_gene_info' or 'search_by_gene_symbol', nor does it mention prerequisites or exclusions. It implies usage for protein-specific queries but lacks explicit context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for genes by symbol with optional organism filter
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Gene symbol (e.g., 'BRCA1', 'TP53') | |
| organism | No | Optional organism filter (e.g., 'human', 'Homo sapiens') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it's a search operation, implying read-only behavior, but doesn't detail aspects like response format, error handling, rate limits, or whether it returns partial matches. For a tool with no annotations, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded in a single sentence, efficiently conveying the core function without unnecessary details. However, it could be slightly improved by structuring to highlight key points more clearly, but it avoids waste and is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose and parameters but lacks details on output, error cases, and differentiation from siblings. Without an output schema, more information on return values would be helpful, making it minimally viable but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents both parameters ('symbol' and 'organism') with descriptions. The description adds marginal value by emphasizing the optionality of 'organism' but doesn't provide additional semantics beyond what the schema offers, such as format examples or constraints. Baseline 3 is appropriate when the schema handles most documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for genes by symbol with optional organism filter.' It specifies the verb ('Search'), resource ('genes'), and key parameter ('symbol'), making the function evident. However, it doesn't explicitly differentiate from sibling tools like 'search_genes' or 'fetch_gene_info,' which might offer similar functionality, so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance, mentioning an 'optional organism filter' but not explaining when to use this tool versus alternatives like 'search_genes' or 'fetch_gene_info.' There's no context on when this tool is preferred, what it returns, or any prerequisites, leaving usage unclear in relation to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for genes in NCBI database using a query
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (gene name, symbol, etc.) | |
| max_results | No | Maximum number of results to return (default: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the basic function but doesn't mention important behavioral traits like whether this is a read-only operation, what authentication might be needed, rate limits, what happens with no results, or what format results come in. For a search tool with zero annotation coverage, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the core function without unnecessary words. It's appropriately sized for a simple search tool and front-loads the essential information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is insufficiently complete. For a search tool that likely returns structured gene data, the description should at minimum indicate what kind of information is returned (IDs, names, summaries?) and mention any important constraints. The current description leaves too much undefined for proper agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters (query and max_results). The description doesn't add any parameter semantics beyond what's in the schema - it doesn't explain query syntax examples, what 'gene name, symbol, etc.' means practically, or how max_results affects performance. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search for genes') and the target resource ('NCBI database'), providing a specific verb+resource combination. However, it doesn't differentiate this tool from its siblings (fetch_gene_info, fetch_protein_info, search_by_gene_symbol), which likely have overlapping or related functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus its siblings. There's no mention of alternatives, exclusions, or specific contexts where this search tool is preferred over fetch_gene_info or search_by_gene_symbol. The agent must infer usage from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
fetch_gene_infofetch_protein_infosearch_by_gene_symbolsearch_genesScored 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.
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.
Bioinformatics MCP for genomic variant interpretation, gene-disease evidence and literature.
MCP server for querying BrainKB, a knowledge base for neuroscience knowledge graphs.