MCP (Model Context Protocol) server for OpenGenes database This server implements the Model Context Protocol (MCP) for OpenGenes, providing a standardized interface for accessing aging and longevity research data. MCP enables AI assistants and agents to query comprehensive biomedical datasets through structured interfaces. The server automatically downloads the latest OpenGenes database and docume
Add this skill
npx mdskills install longevity-genie/opengenes-mcpWell-documented MCP server providing SQL access to aging/longevity genetics data with auto-updates
1# opengenes-mcp23[](https://github.com/longevity-genie/opengenes-mcp/actions/workflows/test.yml)4[](https://badge.fury.io/py/opengenes-mcp)5[](https://www.python.org/downloads/)6[](https://opensource.org/licenses/MIT)7[](https://github.com/psf/black)89MCP (Model Context Protocol) server for OpenGenes database1011This server implements the Model Context Protocol (MCP) for OpenGenes, providing a standardized interface for accessing aging and longevity research data. MCP enables AI assistants and agents to query comprehensive biomedical datasets through structured interfaces.1213The server automatically downloads the latest OpenGenes database and documentation from [Hugging Face Hub](https://huggingface.co/longevity-genie/bio-mcp-data) (specifically from the `opengenes` folder), ensuring you always have access to the most up-to-date data without manual file management.1415The OpenGenes database contains:1617- **lifespan_change**: Experimental data about genetic interventions and their effects on lifespan across model organisms18- **gene_criteria**: Criteria classifications for aging-related genes (12 different categories)19- **gene_hallmarks**: Hallmarks of aging associated with specific genes20- **longevity_associations**: Genetic variants associated with longevity from population studies2122If you want to understand more about what the Model Context Protocol is and how to use it more efficiently, you can take the [DeepLearning AI Course](https://www.deeplearning.ai/short-courses/mcp-build-rich-context-ai-apps-with-anthropic/) or search for MCP videos on YouTube.2324## 🏆 Part of Holy Bio MCP Framework2526This MCP server is part of the **[Holy Bio MCP](https://github.com/longevity-genie/holy-bio-mcp)** project - a unified framework for bioinformatics research that **won the Bio x AI Hackathon 2025** and continues to be actively developed and extended after the victory.2728The Holy Bio MCP framework brings together multiple specialized MCP servers into a cohesive ecosystem for advanced biological research:2930- **[gget-mcp](https://github.com/longevity-genie/gget-mcp)** - Genomics & sequence analysis toolkit31- **[opengenes-mcp](https://github.com/longevity-genie/opengenes-mcp)** - Aging & longevity genetics (this server)32- **[synergy-age-mcp](https://github.com/longevity-genie/synergy-age-mcp)** - Synergistic genetic interactions in longevity33- **[biothings-mcp](https://github.com/longevity-genie/biothings-mcp)** - Foundational biological data from BioThings.io34- **[pharmacology-mcp](https://github.com/antonkulaga/pharmacology-mcp)** - Drug, target & ligand data3536Together, these servers provide 50+ specialized bioinformatics functions that can work seamlessly together in AI-driven research workflows. Learn more about the complete framework at [github.com/longevity-genie/holy-bio-mcp](https://github.com/longevity-genie/holy-bio-mcp).3738## Usage Example3940Here's how the OpenGenes MCP server works in practice with AI assistants:41424344*Example showing how to query the OpenGenes database through an AI assistant using natural language, which gets translated to SQL queries via the MCP server. You can use this database both in chat interfaces for research questions and in AI-based development tools (like Cursor, Windsurf, VS Code with Copilot) to significantly improve your bioinformatics productivity by having direct access to aging and longevity research data while coding.*4546## About MCP (Model Context Protocol)4748MCP is a protocol that bridges the gap between AI systems and specialized domain knowledge. It enables:4950- **Structured Access**: Direct connection to authoritative aging and longevity research data51- **Natural Language Queries**: Simplified interaction with specialized databases through SQL52- **Type Safety**: Strong typing and validation through FastMCP53- **AI Integration**: Seamless integration with AI assistants and agents5455## Data Source and Updates5657The OpenGenes MCP server automatically downloads data from the [longevity-genie/bio-mcp-data](https://huggingface.co/longevity-genie/bio-mcp-data) repository on Hugging Face Hub. This ensures:5859- **Always Up-to-Date**: Automatic access to the latest OpenGenes database without manual updates60- **Reliable Distribution**: Centralized data hosting with version control and change tracking61- **Efficient Caching**: Downloaded files are cached locally to minimize network requests62- **Fallback Support**: Local fallback files are supported for development and offline use6364The data files are stored in the `opengenes` subfolder of the Hugging Face repository and include:65- `open_genes.sqlite` - The complete OpenGenes database66- `prompt.txt` - Database schema documentation and usage guidelines6768## Available Tools6970This server provides three main tools for interacting with the OpenGenes database:71721. **`opengenes_db_query(sql: str)`** - Execute read-only SQL queries against the OpenGenes database732. **`opengenes_get_schema_info()`** - Get detailed schema information including tables, columns, and enumerations743. **`opengenes_example_queries()`** - Get a list of example SQL queries with descriptions7576## Available Resources77781. **`resource://db-prompt`** - Complete database schema documentation and usage guidelines792. **`resource://schema-summary`** - Formatted summary of tables and their purposes8081## Quick Start8283### Installing uv8485```bash86# Download and install uv87curl -LsSf https://astral.sh/uv/install.sh | sh8889# Verify installation90uv --version91uvx --version92```9394uvx is a very nice tool that can run a python package installing it if needed.9596### Running with uvx9798You can run the opengenes-mcp server directly using uvx without cloning the repository:99100```bash101# Run the server in streamed http mode (default)102uvx opengenes-mcp103```104105<details>106<summary>Other uvx modes (STDIO, HTTP, SSE)</summary>107108#### STDIO Mode (for MCP clients that require stdio, can be useful when you want to save files)109110```bash111# Or explicitly specify stdio mode112uvx opengenes-mcp stdio113```114115#### HTTP Mode (Web Server)116```bash117# Run the server in streamable HTTP mode on default (3001) port118uvx opengenes-mcp server119120# Run on a specific port121uvx opengenes-mcp server --port 8000122```123124#### SSE Mode (Server-Sent Events)125```bash126# Run the server in SSE mode127uvx opengenes-mcp sse128```129130</details>131132In cases when there are problems with uvx often they can be caused by clenaing uv cache:133```134uv cache clean135```136137The HTTP mode will start a web server that you can access at `http://localhost:3001/mcp` (with documentation at `http://localhost:3001/docs`). The STDIO mode is designed for MCP clients that communicate via standard input/output, while SSE mode uses Server-Sent Events for real-time communication.138139**Note:** Currently, we do not have a Swagger/OpenAPI interface, so accessing the server directly in your browser will not show much useful information. To explore the available tools and capabilities, you should either use the MCP Inspector (see below) or connect through an MCP client to see the available tools.140141## Configuring your AI Client (Anthropic Claude Desktop, Cursor, Windsurf, etc.)142143### Quick Configuration Example144145Here's what you can copy directly into your Claude Desktop or Cursor MCP configuration:146147```json148{149 "mcpServers": {150 "opengenes-mcp": {151 "command": "uvx",152 "args": ["opengenes-mcp"],153 "env": {154 "MCP_TRANSPORT": "stdio"155 }156 }157 }158}159```160161### Alternative: Using Preconfigured Files162163We also provide preconfigured JSON files for different use cases:164165- **For STDIO mode (recommended):** Use `mcp-config-stdio.json`166- **For HTTP mode:** Use `mcp-config.json`167- **For local development:** Use `mcp-config-stdio-debug.json`168169### Configuration Video Tutorial170171For a visual guide on how to configure MCP servers with AI clients, check out our [configuration tutorial video](https://www.youtube.com/watch?v=Xo0sHWGJvE0) for our sister MCP server (biothings-mcp). The configuration principles are exactly the same for the OpenGenes MCP server - just use the appropriate JSON configuration files provided above.172173### Inspecting OpenGenes MCP server174175<details>176<summary>Using MCP Inspector to explore server capabilities</summary>177178If you want to inspect the methods provided by the MCP server, use npx (you may need to install nodejs and npm):179180For STDIO mode with uvx:181```bash182npx @modelcontextprotocol/inspector --config mcp-config-stdio.json --server opengenes-mcp183```184185For HTTP mode (ensure server is running first):186```bash187npx @modelcontextprotocol/inspector --config mcp-config.json --server opengenes-mcp188```189190For local development:191```bash192npx @modelcontextprotocol/inspector --config mcp-config-stdio-debug.json --server opengenes-mcp193```194195You can also run the inspector manually and configure it through the interface:196```bash197npx @modelcontextprotocol/inspector198```199200After that you can explore the tools and resources with MCP Inspector at http://127.0.0.1:6274 (note, if you run inspector several times it can change port)201202</details>203204### Integration with AI Systems205206Simply point your AI client (like Cursor, Windsurf, ClaudeDesktop, VS Code with Copilot, or [others](https://github.com/punkpeye/awesome-mcp-clients)) to use the appropriate configuration file from the repository.207208## Repository setup209210```bash211# Clone the repository212git clone https://github.com/longevity-genie/opengenes-mcp.git213cd opengenes-mcp214uv sync215```216217### Running the MCP Server218219If you already cloned the repo you can run the server with uv:220221```bash222# Start the MCP server locally (HTTP mode)223uv run server224225# Or start in STDIO mode226uv run stdio227228# Or start in SSE mode229uv run sse230```231232## Database Schema233234<details>235<summary>Detailed schema information</summary>236237### Main Tables238239- **lifespan_change** (47 columns): Experimental lifespan data with intervention details across model organisms240- **gene_criteria** (2 columns): Gene classifications by aging criteria (12 different categories)241- **gene_hallmarks** (2 columns): Hallmarks of aging mappings for genes242- **longevity_associations** (11 columns): Population genetics longevity data from human studies243244### Key Fields245246- **HGNC**: Gene symbol (primary identifier across all tables)247- **model_organism**: Research organism (mouse, C. elegans, fly, etc.)248- **effect_on_lifespan**: Direction of lifespan change (increases/decreases/no change)249- **intervention_method**: Method of genetic intervention (knockout, overexpression, etc.)250- **criteria**: Aging-related gene classification (12 categories)251- **hallmarks of aging**: Biological aging processes associated with genes252253</details>254255## Example Queries256257<details>258<summary>Sample SQL queries for common research questions</summary>259260```sql261-- Get top genes with most lifespan experiments262SELECT HGNC, COUNT(*) as experiment_count263FROM lifespan_change264WHERE HGNC IS NOT NULL265GROUP BY HGNC266ORDER BY experiment_count DESC267LIMIT 10;268269-- Find genes that increase lifespan in mice270SELECT DISTINCT HGNC, effect_on_lifespan271FROM lifespan_change272WHERE model_organism = 'mouse'273AND effect_on_lifespan = 'increases lifespan'274AND HGNC IS NOT NULL;275276-- Get hallmarks of aging for genes277SELECT HGNC, "hallmarks of aging"278FROM gene_hallmarks279WHERE "hallmarks of aging" LIKE '%mitochondrial%';280281-- Find longevity associations by ethnicity282SELECT HGNC, "polymorphism type", "nucleotide substitution", ethnicity283FROM longevity_associations284WHERE ethnicity LIKE '%Italian%';285286-- Find genes with both lifespan effects and longevity associations287SELECT DISTINCT lc.HGNC288FROM lifespan_change lc289INNER JOIN longevity_associations la ON lc.HGNC = la.HGNC290WHERE lc.HGNC IS NOT NULL;291```292293</details>294295## Safety Features296297- **Read-only access**: Only SELECT queries are allowed298- **Input validation**: Blocks INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE operations299- **Error handling**: Comprehensive error handling with informative messages300301## Testing & Verification302303The MCP server is provided with comprehensive tests including LLM-as-a-judge tests that evaluate the quality of responses to complex queries. However, LLM-based tests are disabled by default in CI to save costs.304305### Environment Setup for LLM Agent Tests306307If you want to run LLM agent tests that use MCP functions with Gemini models, you need to set up a `.env` file with your Gemini API key:308309```bash310# Create a .env file in the project root311echo "GEMINI_API_KEY=your-gemini-api-key-here" > .env312```313314**Note:** The `.env` file and Gemini API key are only required for running LLM agent tests. All other tests and basic MCP server functionality work without any API keys.315316### Running Tests317318Run tests for the MCP server:319```bash320uv run pytest -vvv -s321```322323You can also run manual tests:324```bash325uv run python test/manual_test_questions.py326```327328You can use MCP inspector with locally built MCP server same way as with uvx.329330*Note: Using the MCP Inspector is optional. Most MCP clients (like Cursor, Windsurf, etc.) will automatically display the available tools from this server once configured. However, the Inspector can be useful for detailed testing and exploration.*331332*If you choose to use the Inspector via `npx`, ensure you have Node.js and npm installed. Using [nvm](https://github.com/nvm-sh/nvm) (Node Version Manager) is recommended for managing Node.js versions.*333334## Example questions that MCP helps to answer335336<details>337<summary>Research questions you can explore with this MCP server</summary>338339* Interventions on which genes extended mice lifespan most of all?340* Which knockdowns were most lifespan extending on model animals?341* What processes are improved in GHR knockout mice?342* Which genetic intervention led to the greatest increase in lifespan in flies?343* To what extent did the lifespan increase in mice overexpressing VEGFA?344* Are there any liver-specific interventions that increase lifespan in mice?345* Which gene-longevity association is confirmed by the greatest number of studies?346* What polymorphisms in FOXO3 are associated with human longevity?347* In which ethnic groups was the association of the APOE gene with longevity shown?348* Is the INS gene polymorphism associated with longevity?349* What genes are associated with transcriptional alterations?350* Which hallmarks are associated with the KL gene?351* How many genes are associated with longevity in humans?352* What types of studies have been conducted on the IGF1R gene?353* What evidence of the link between PTEN and aging do you know?354* What genes are associated with both longevity and altered expression in aged humans?355* Is the expression of the ACE2 gene altered with aging in humans?356* What genes need to be downregulated in worms to extend their lifespan?357358</details>359360## Contributing361362We welcome contributions from the community! 🎉 Whether you're a researcher, developer, or enthusiast interested in aging and longevity research, there are many ways to get involved:363364**We especially encourage you to try our MCP server and share your feedback with us!** Your experience using the server, any issues you encounter, and suggestions for improvement are incredibly valuable for making this tool better for the entire research community.365366### Ways to Contribute367368- **🐛 Bug Reports**: Found an issue? Please open a GitHub issue with detailed information369- **💡 Feature Requests**: Have ideas for new functionality? We'd love to hear them!370- **📝 Documentation**: Help improve our documentation, examples, or tutorials371- **🧪 Testing**: Add test cases, especially for edge cases or new query patterns372- **🔍 Data Quality**: Help identify and report data inconsistencies or suggest improvements373- **🚀 Performance**: Optimize queries, improve caching, or enhance server performance374- **🌐 Integration**: Create examples for new MCP clients or AI systems375- **🎥 Tutorials & Videos**: Create tutorials, video guides, or educational content showing how to use MCP servers376- **📖 User Stories**: Share your research workflows and success stories using our MCP servers377- **🤝 Community Outreach**: Help us evangelize MCP adoption in the bioinformatics community378379**Tutorials, videos, and user stories are especially valuable to us!** We're working to push the bioinformatics community toward AI adoption, and real-world examples of how researchers use our MCP servers (this one and others we develop) help demonstrate the practical benefits and encourage wider adoption.380381### Getting Started3823831. Fork the repository3842. Create a feature branch (`git checkout -b feature/amazing-feature`)3853. Make your changes and add tests3864. Run the test suite (`uv run pytest`)3875. Commit your changes (`git commit -m 'Add amazing feature'`)3886. Push to your branch (`git push origin feature/amazing-feature`)3897. Open a Pull Request390391### Development Guidelines392393- Follow the existing code style (we use `black` for formatting)394- Add tests for new functionality395- Update documentation as needed396- Keep commits focused and write clear commit messages397398### Questions or Ideas?399400Don't hesitate to open an issue for discussion! We're friendly and always happy to help newcomers get started. Your contributions help advance open science and longevity research for everyone. 🧬✨401402## Known Issues403404### Database Coverage405Currently, this MCP server uses only a subset of the complete OpenGenes database. The full OpenGenes database contains additional tables and data that are not yet included in our MCP implementation. **We need contributors to help extend support for the complete database!** If you're interested in helping expand the database coverage, please see our [Contributing](#contributing) section.406407### Test Coverage408While we provide comprehensive tests including LLM-as-a-judge evaluations, not all test cases have been manually verified against the actual OpenGenes web interface. Some automated test results may need manual validation to ensure accuracy. Contributions to improve test coverage and validation are welcome.409410## License411412This project is licensed under the MIT License.413414## Acknowledgments415416- [OpenGenes Database](https://open-genes.com/) for the comprehensive aging research data417 - Rafikova E, Nemirovich-Danchenko N, Ogmen A, Parfenenkova A, Velikanova A, Tikhonov S, Peshkin L, Rafikov K, Spiridonova O, Belova Y, Glinin T, Egorova A, Batin M. Open Genes-a new comprehensive database of human genes associated with aging and longevity. Nucleic Acids Res. 2024 Jan 5;52(D1):D950-D962. doi: 10.1093/nar/gkad712. PMID: 37665017; PMCID: PMC10768108.418- [Model Context Protocol](https://modelcontextprotocol.io/) for the protocol specification419- [FastMCP](https://github.com/jlowin/fastmcp) for the MCP server framework420421This project is part of the [Longevity Genie](https://github.com/longevity-genie) organization, which develops open-source AI assistants and libraries for health, genetics, and longevity research.422423### Other MCP Servers in the Holy Bio MCP Framework424425This server is part of the complete **[Holy Bio MCP](https://github.com/longevity-genie/holy-bio-mcp)** framework, which includes:426427- **[gget-mcp](https://github.com/longevity-genie/gget-mcp)** - Powerful bioinformatics toolkit for genomics queries and analysis428- **[synergy-age-mcp](https://github.com/longevity-genie/synergy-age-mcp)** - Database of synergistic and antagonistic genetic interactions in longevity429- **[biothings-mcp](https://github.com/longevity-genie/biothings-mcp)** - Access to BioThings.io APIs for comprehensive gene, variant, chemical, and taxonomic data430- **[pharmacology-mcp](https://github.com/antonkulaga/pharmacology-mcp)** - Access to the Guide to PHARMACOLOGY database for drug, target, and ligand information431432The framework provides unified configuration files that enable all servers at once, making it easy to access 50+ specialized bioinformatics functions through a single setup. This award-winning project continues to evolve as a comprehensive platform for AI-driven biological research.433434We are supported by:435436[](https://heales.org/)437438*HEALES - Healthy Life Extension Society*439440and441442[](https://ibima.med.uni-rostock.de/)443444[IBIMA - Institute for Biostatistics and Informatics in Medicine and Ageing Research](https://ibima.med.uni-rostock.de/)445
Full transparency — inspect the skill content before installing.