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 ## 📦 Installation ### From Source (Development) ```bash # Clone the repository git clone <repository-url> cd ncbi_gene_mcp_client # Install in development mode pip install -e . ``` ### From PyPI (when available) ```bash pip install ncbi_gene_mcp_client ``` ## 🔧 Usage ### Command Line Interface After installation, you can use the CLI commands: #### Demo (Quick Start) ```bash ncbi-gene-client demo ``` #### Search for genes ```bash ncbi-gene-client search-genes "BRCA1" ncbi-gene-client search-genes "breast cancer" --max-results 10 ``` #### Get gene information by ID ```bash ncbi-gene-client gene-info 672 # BRCA1 gene ``` #### Search by gene symbol ```bash ncbi-gene-client search-symbol BRCA1 --organism human ncbi-gene-client search-symbol TP53 ``` #### Get protein information ```bash ncbi-gene-client protein-info <protein_id> ``` #### With NCBI credentials (recommended) ```bash ncbi-gene-client --email your@email.com --api-key YOUR_API_KEY demo ``` ### Python API ```python 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: ```bash 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 ```python 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 ```python # 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 ```python # 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 ```python { "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 ```python { "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: ```python client = NCBIGeneMCPClientBridge(email="your@email.com") ``` For higher rate limits, you can also provide an API key: ```python 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: ```bash # 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 ```bash # 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](https://www.ncbi.nlm.nih.gov/books/NBK25501/) - [NCBI Gene Database](https://www.ncbi.nlm.nih.gov/gene/) - [E-utilities API Documentation](https://www.ncbi.nlm.nih.gov/books/NBK25499/) ## 📄 License This project is licensed under the MIT License - see the [LICENSE](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: ```python 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: ```json { "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 ```bash # 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.