MCP (Model Context Protocol) server for SynergyAge database This server implements the Model Context Protocol (MCP) for SynergyAge, providing a standardized interface for accessing synergistic genetic intervention and aging research data. MCP enables AI assistants and agents to query comprehensive longevity datasets through structured interfaces. The server automatically downloads the latest Syner
Add this skill
npx mdskills install longevity-genie/synergy-age-mcpWell-documented MCP server providing SQL access to curated genetic aging research data
1# synergy-age-mcp23[](https://github.com/longevity-genie/synergy-age-mcp/actions/workflows/test.yml)4[](https://github.com/longevity-genie/synergy-age-mcp/actions/workflows/ci.yml)5[](https://badge.fury.io/py/synergy-age-mcp)6[](https://www.python.org/downloads/)7[](https://opensource.org/licenses/MIT)8[](https://github.com/psf/black)910MCP (Model Context Protocol) server for SynergyAge database1112This server implements the Model Context Protocol (MCP) for SynergyAge, providing a standardized interface for accessing synergistic genetic intervention and aging research data. MCP enables AI assistants and agents to query comprehensive longevity datasets through structured interfaces.1314The server automatically downloads the latest SynergyAge database and documentation from [Hugging Face Hub](httpss://huggingface.co/datasets/longevity-genie/bio-mcp-data) (specifically from the `synergy-age` folder), ensuring you always have access to the most up-to-date data without manual file management.1516The SynergyAge database contains:1718- **models**: Experimentally validated genetic interventions and their effects on lifespan across model organisms19- **model_interactions**: Synergistic, antagonistic, and epistatic interactions between genetic interventions20- **Data for multiple model organisms**: C. elegans, Drosophila melanogaster, mice, and other aging research models21- **Quantitative lifespan effects**: Precise measurements of intervention effectiveness2223## Usage Example24252627Here's how the SynergyAge MCP server works in practice with AI assistants:2829*Example showing how to query the SynergyAge 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 aging and longevity research productivity by having direct access to synergistic intervention data while coding.*3031## Understanding Genetic Interactions3233The SynergyAge database focuses on different types of genetic interactions that affect lifespan:34353637*Figure: Types of genetic interactions in longevity research - synergistic, antagonistic, and additive effects between genetic interventions (Source: [SynergyAge.info](https://www.synergyage.info))*3839- **Synergistic interactions**: Combined interventions produce greater effects than the sum of individual effects40- **Antagonistic interactions**: Combined interventions produce smaller effects than expected, with one intervention suppressing another41- **Additive interactions**: Combined interventions produce effects equal to the sum of individual effects4243If 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.4445## About MCP (Model Context Protocol)4647MCP is a protocol that bridges the gap between AI systems and specialized domain knowledge. It enables:4849- **Structured Access**: Direct connection to authoritative synergistic aging intervention data50- **Natural Language Queries**: Simplified interaction with specialized databases through SQL51- **Type Safety**: Strong typing and validation through FastMCP52- **AI Integration**: Seamless integration with AI assistants and agents5354## About SynergyAge5556SynergyAge is a curated database containing experimentally validated data on genetic interventions affecting lifespan across multiple model organisms. The database focuses on both single-gene mutants and multi-gene combinations to understand genetic interactions in aging.5758### Data Validation & Quality5960The SynergyAge data undergoes rigorous validation at three levels:61621. **Curation Level**: Only papers with experimentally validated results are selected for inclusion632. **Import Validation**: Automatic checks ensure no missing values or incorrect data formats643. **Post-deployment**: Manual investigation of outliers and random entries, with lifespan distributions plotted for each mutant at different temperatures6566All survival curves from included papers are manually verified to ensure data accuracy.6768### Key Features6970- **Comprehensive Search**: Text search supporting multiple genes (comma or semicolon separated)71- **Categorized Results**: Search results grouped into four categories:72 - Mutants with interventions in all searched genes73 - Single-gene mutants (1-mutants)74 - Multi-gene mutants with subset interventions (n-mutants)75 - Extended combinations including additional genes76- **Interactive Network Visualization**: Visual exploration of mutant relationships with nodes representing lifespan models and edges showing genetic intervention relationships77- **Epistasis Analysis**: Assessment of genetic interactions between modulated genes78- **External Integration**: Links to KEGG pathways and model-specific databases for enhanced context7980## Data Source and Updates8182The SynergyAge MCP server automatically downloads data from the [longevity-genie/bio-mcp-data](httpss://huggingface.co/datasets/longevity-genie/bio-mcp-data) repository on Hugging Face Hub. This ensures:8384- **Always Up-to-Date**: Automatic access to the latest SynergyAge database without manual updates85- **Reliable Distribution**: Centralized data hosting with version control and change tracking86- **Efficient Caching**: Downloaded files are cached locally to minimize network requests87- **Fallback Support**: Local fallback files are supported for development and offline use8889The data files are stored in the `synergy-age` subfolder of the Hugging Face repository and include:90- `synergy-age.sqlite` - The complete SynergyAge database91- `synergyage_prompt.txt` - Database schema documentation and usage guidelines9293## Available Tools9495This server provides three main tools for interacting with the SynergyAge database:96971. **`synergyage_db_query(sql: str)`** - Execute read-only SQL queries against the SynergyAge database982. **`synergyage_get_schema_info()`** - Get detailed schema information including tables, columns, and data descriptions993. **`synergyage_example_queries()`** - Get a list of example SQL queries with descriptions100101## Available Resources1021031. **`resource://db-prompt`** - Complete database schema documentation and usage guidelines1042. **`resource://schema-summary`** - Formatted summary of tables and their purposes105106## Quick Start107108### Installing uv109110```bash111# Download and install uv112curl -LsSf https://astral.sh/uv/install.sh | sh113114# Verify installation115uv --version116uvx --version117```118119uvx is a very nice tool that can run a python package installing it if needed.120121### Running with uvx122123You can run the synergy-age-mcp server directly using uvx without cloning the repository:124125```bash126# Run the server in streamed http mode (default)127uvx synergy-age-mcp128```129130<details>131<summary>Other uvx modes (STDIO, HTTP, SSE)</summary>132133#### STDIO Mode (for MCP clients that require stdio, can be useful when you want to save files)134135```bash136# Or explicitly specify stdio mode137uvx synergy-age-mcp stdio138```139140#### HTTP Mode (Web Server)141```bash142# Run the server in streamable HTTP mode on default (3002) port143uvx synergy-age-mcp server144145# Run on a specific port146uvx synergy-age-mcp server --port 8000147```148149#### SSE Mode (Server-Sent Events)150```bash151# Run the server in SSE mode152uvx synergy-age-mcp sse153```154155</details>156157In cases when there are problems with uvx often they can be caused by cleaning uv cache:158```159uv cache clean160```161162The HTTP mode will start a web server that you can access at `http://localhost:3002/mcp` (with documentation at `http://localhost:3002/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.163164**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.165166## Configuring your AI Client (Anthropic Claude Desktop, Cursor, Windsurf, etc.)167168We provide preconfigured JSON files for different use cases:169170- **For STDIO mode (recommended):** Use `mcp-config-stdio.json`171- **For HTTP mode:** Use `mcp-config.json`172- **For local development:** Use `mcp-config-stdio-debug.json`173174### Configuration Video Tutorial175176For 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 SynergyAge MCP server - just use the appropriate JSON configuration files provided above.177178### Inspecting SynergyAge MCP server179180<details>181<summary>Using MCP Inspector to explore server capabilities</summary>182183If you want to inspect the methods provided by the MCP server, use npx (you may need to install nodejs and npm):184185For STDIO mode with uvx:186```bash187npx @modelcontextprotocol/inspector --config mcp-config-stdio.json --server synergy-age-mcp188```189190For HTTP mode (ensure server is running first):191```bash192npx @modelcontextprotocol/inspector --config mcp-config.json --server synergy-age-mcp193```194195For local development:196```bash197npx @modelcontextprotocol/inspector --config mcp-config-stdio-debug.json --server synergy-age-mcp198```199200You can also run the inspector manually and configure it through the interface:201```bash202npx @modelcontextprotocol/inspector203```204205After 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)206207</details>208209### Integration with AI Systems210211Simply 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.212213## Repository setup214215```bash216# Clone the repository217git clone https://github.com/longevity-genie/synergy-age-mcp.git218cd synergy-age-mcp219uv sync220```221222### Running the MCP Server223224If you already cloned the repo you can run the server with uv:225226```bash227# Start the MCP server locally (HTTP mode)228uv run server229230# Or start in STDIO mode231uv run stdio232233# Or start in SSE mode234uv run sse235```236237## Database Schema238239<details>240<summary>Detailed schema information</summary>241242### Main Tables243244- **models** (12 columns): Experimental genetic intervention data with lifespan effects across model organisms245- **model_interactions** (3 columns): Synergistic, antagonistic, and epistatic interactions between genetic interventions246247### Key Fields248249- **id**: Unique identifier for each genetic intervention model250- **tax_id**: NCBI Taxonomy ID for the model organism251- **name**: Descriptive name of the genetic intervention252- **genes**: Target genes for the intervention253- **temp**: Experimental temperature conditions254- **lifespan**: Measured lifespan values255- **effect**: Quantitative effect on lifespan (percentage change)256- **details**: Detailed description of the intervention method257- **interaction_type**: Classification of genetic interactions258- **phenotype_comparison**: Description of interaction effects259260</details>261262## Example Queries263264<details>265<summary>Sample SQL queries for common research questions</summary>266267```sql268-- Get top genetic interventions with highest lifespan effects269SELECT genes, effect, details, model_organism270FROM models271WHERE effect > 0272ORDER BY effect DESC273LIMIT 10;274275-- Find synergistic interactions in C. elegans276SELECT m1.genes as gene1, m2.genes as gene2, mi.phenotype_comparison277FROM model_interactions mi278JOIN models m1 ON mi.id1 = m1.id279JOIN models m2 ON mi.id2 = m2.id280WHERE m1.tax_id = 6239 AND m2.tax_id = 6239281AND mi.phenotype_comparison LIKE '%synergistic%';282283-- Compare insulin signaling pathway effects across organisms284SELECT tax_id, genes, effect, details285FROM models286WHERE genes LIKE '%daf-2%' OR genes LIKE '%InR%' OR genes LIKE '%IGF1R%'287ORDER BY tax_id, effect DESC;288289-- Find interventions with antagonistic interactions290SELECT m1.genes, m2.genes, mi.phenotype_comparison291FROM model_interactions mi292JOIN models m1 ON mi.id1 = m1.id293JOIN models m2 ON mi.id2 = m2.id294WHERE mi.phenotype_comparison LIKE '%antagonistic%'295 OR mi.phenotype_comparison LIKE '%suppress%';296297-- Get average lifespan effects by organism298SELECT tax_id, COUNT(*) as intervention_count,299 AVG(effect) as avg_effect,300 MAX(effect) as max_effect301FROM models302WHERE effect IS NOT NULL303GROUP BY tax_id304ORDER BY avg_effect DESC;305```306307</details>308309## Safety Features310311- **Read-only access**: Only SELECT queries are allowed312- **Input validation**: Blocks INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE operations313- **Error handling**: Comprehensive error handling with informative messages314315## Testing & Verification316317The 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.318319### Environment Setup for LLM Agent Tests320321If 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:322323```bash324# Create a .env file in the project root325echo "GEMINI_API_KEY=your-gemini-api-key-here" > .env326```327328**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.329330### Running Tests331332Run tests for the MCP server:333```bash334uv run pytest -vvv -s335```336337You can also run manual tests:338```bash339uv run python tests/manual_test_questions.py340```341342You can use MCP inspector with locally built MCP server same way as with uvx.343344*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.*345346*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.*347348## Example questions that MCP helps to answer349350<details>351<summary>Research questions you can explore with this MCP server</summary>352353* What are the synergistic interactions involving daf-2 mutations in C. elegans?354* Which genetic interventions show the largest positive effects on lifespan in C. elegans?355* What types of synergistic interactions are found between longevity interventions?356* How do insulin signaling pathway interventions compare across different model organisms?357* Which interventions show negative effects on lifespan and why?358* Which genetic interventions show the strongest synergistic effects in C. elegans?359* What are the most effective single-gene interventions for lifespan extension across model organisms?360* How do insulin signaling pathway interventions compare between C. elegans, Drosophila, and mice?361* Which genetic combinations show antagonistic interactions that reduce lifespan benefits?362* What is the relationship between daf-2 and daf-16 mutations in C. elegans longevity?363* Which interventions target similar pathways but show different interaction patterns?364* What are the temperature-dependent effects of genetic interventions on lifespan?365* Which model organism shows the highest average lifespan extension from genetic interventions?366* How do caloric restriction mimetics interact with other longevity interventions?367* What genetic interventions show consistent effects across different strains or conditions?368* Which pathways are most commonly targeted in successful longevity interventions?369* How do single mutants compare to double or triple mutants in terms of lifespan effects?370* What is the distribution of positive vs negative lifespan effects across all interventions?371* Which genes show the most experimental validation across different studies?372* How do oxidative stress response pathways interact with other longevity mechanisms?373* What interventions show epistatic relationships indicating pathway dependencies?374* Which genetic combinations produce super-additive longevity effects?375* How do mitochondrial interventions synergize with other cellular pathways?376377</details>378379## Contributing380381We 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:382383**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.384385### Ways to Contribute386387- **🐛 Bug Reports**: Found an issue? Please open a GitHub issue with detailed information388- **💡 Feature Requests**: Have ideas for new functionality? We'd love to hear them!389- **📝 Documentation**: Help improve our documentation, examples, or tutorials390- **🧪 Testing**: Add test cases, especially for edge cases or new query patterns391- **🔍 Data Quality**: Help identify and report data inconsistencies or suggest improvements392- **🚀 Performance**: Optimize queries, improve caching, or enhance server performance393- **🌐 Integration**: Create examples for new MCP clients or AI systems394- **🎥 Tutorials & Videos**: Create tutorials, video guides, or educational content showing how to use MCP servers395- **📖 User Stories**: Share your research workflows and success stories using our MCP servers396- **🤝 Community Outreach**: Help us evangelize MCP adoption in the aging research community397398**Tutorials, videos, and user stories are especially valuable to us!** We're working to push the aging research community toward AI adoption, and real-world examples of how researchers use our MCP servers help demonstrate the practical benefits and encourage wider adoption.399400### Getting Started4014021. Fork the repository4032. Create a feature branch (`git checkout -b feature/amazing-feature`)4043. Make your changes and add tests4054. Run the test suite (`uv run pytest`)4065. Commit your changes (`git commit -m 'Add amazing feature'`)4076. Push to your branch (`git push origin feature/amazing-feature`)4087. Open a Pull Request409410### Development Guidelines411412- Follow the existing code style (we use `black` for formatting)413- Add tests for new functionality414- Update documentation as needed415- Keep commits focused and write clear commit messages416417### Questions or Ideas?418419Don'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. 🧬✨420421## Known Issues422423### Database Coverage424The SynergyAge MCP server currently provides access to the core experimental data tables. Future versions may include additional metadata tables and extended functionality based on community feedback and research needs.425426### Test Coverage427While we provide comprehensive tests including LLM-as-a-judge evaluations, not all test cases have been manually verified against the actual SynergyAge web interface. Some automated test results may need manual validation to ensure accuracy. Contributions to improve test coverage and validation are welcome.428429## License430431This project is licensed under the MIT License.432433## Citations434435If you use SynergyAge data in your research, please cite:436437Bunu, G., Toren, D., Ion, C. et al. SynergyAge, a curated database for synergistic and antagonistic interactions of longevity-associated genes. *Sci Data* **7**, 366 (2020). https://doi.org/10.1038/s41597-020-00710-z438439## Acknowledgments440441- [SynergyAge Database](https://github.com/gerontomics/synergyage) for the comprehensive synergistic aging intervention data442- [Model Context Protocol](https://modelcontextprotocol.io/) for the protocol specification443- [FastMCP](https://github.com/jlowin/fastmcp) for the MCP server framework444445This 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.446447### Other MCP Servers by Longevity Genie448449We also develop other specialized MCP servers for biomedical research:450451- **[opengenes-mcp](https://github.com/longevity-genie/opengenes-mcp)** - MCP server for OpenGenes database, providing access to aging-related gene data, lifespan experiments, and longevity associations452- **[biothings-mcp](https://github.com/longevity-genie/biothings-mcp)** - MCP server for BioThings.io APIs, providing access to gene annotation (mygene.info), variant annotation (myvariant.info), and chemical compound data (mychem.info)453454We are supported by:455456[](https://heales.org/)457458*HEALES - Healthy Life Extension Society*459460and461462[](https://ibima.med.uni-rostock.de/)463464[IBIMA - Institute for Biostatistics and Informatics in Medicine and Ageing Research](https://ibima.med.uni-rostock.de/)
Full transparency — inspect the skill content before installing.