Opengenes MCP

🚀 opengenes - mcp

opengenes - mcp是一个基于Model Context Protocol（MCP）的服务器，用于访问OpenGenes数据库。它为AI助手和代理提供了标准化接口，可通过结构化接口查询全面的生物医学数据集，助力衰老和长寿研究。

🚀 快速开始

安装uv

# 下载并安装uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 验证安装
uv --version
uvx --version

uvx是一个非常实用的工具，它可以在需要时运行Python包。

使用uvx运行

你可以直接使用uvx运行opengenes - mcp服务器，而无需克隆仓库：

# 以流式HTTP模式运行服务器（默认）
uvx opengenes - mcp

# 或者显式指定stdio模式
uvx opengenes - mcp stdio

# 在默认（3001）端口以可流式HTTP模式运行服务器
uvx opengenes - mcp server

# 在特定端口运行
uvx opengenes - mcp server --port 8000

# 以SSE模式运行服务器
uvx opengenes - mcp sse

若uvx出现问题，通常可通过清理uv缓存解决：

uv cache clean

HTTP模式将启动一个Web服务器，你可以在http://localhost:3001/mcp访问（文档位于http://localhost:3001/docs）。STDIO模式专为通过标准输入输出通信的MCP客户端设计，而SSE模式使用服务器发送事件进行实时通信。

注意：目前我们没有Swagger/OpenAPI接口，因此直接在浏览器中访问服务器不会显示太多有用信息。若要探索可用工具和功能，你应使用MCP Inspector（见下文）或通过MCP客户端连接以查看可用工具。

配置AI客户端（Anthropic Claude Desktop、Cursor、Windsurf等）

我们为不同用例提供了预配置的JSON文件：

• STDIO模式（推荐）：使用mcp - config - stdio.json
• HTTP模式：使用mcp - config.json
• 本地开发：使用mcp - config - stdio - debug.json

配置视频教程

若要获取如何使用AI客户端配置MCP服务器的可视化指南，请查看我们的配置教程视频，该视频针对我们的姊妹MCP服务器（biothings - mcp）。OpenGenes MCP服务器的配置原则完全相同，只需使用上述提供的相应JSON配置文件。

检查OpenGenes MCP服务器

npx @modelcontextprotocol/inspector --config mcp - config - stdio.json --server opengenes - mcp

npx @modelcontextprotocol/inspector --config mcp - config.json --server opengenes - mcp

npx @modelcontextprotocol/inspector --config mcp - config - stdio - debug.json --server opengenes - mcp

npx @modelcontextprotocol/inspector

与AI系统集成

只需将你的AI客户端（如Cursor、Windsurf、ClaudeDesktop、带有Copilot的VS Code或[其他客户端](https://github.com/punkpeye/awesome - mcp - clients)）指向使用仓库中适当的配置文件。

仓库设置

# 克隆仓库
git clone https://github.com/longevity - genie/opengenes - mcp.git
cd opengenes - mcp
uv sync

运行MCP服务器

如果你已经克隆了仓库，可以使用uv运行服务器：

# 在本地启动MCP服务器（HTTP模式）
uv run server

# 或者以STDIO模式启动
uv run stdio

# 或者以SSE模式启动
uv run sse

✨ 主要特性

• 标准化接口：实现了Model Context Protocol（MCP），为访问衰老和长寿研究数据提供标准化接口。
• 自动数据更新：自动从[Hugging Face Hub](https://huggingface.co/longevity - genie/bio - mcp - data)的opengenes文件夹下载最新的OpenGenes数据库和文档，无需手动管理文件。
• 多模式支持：支持多种运行模式，如STDIO、HTTP、SSE，满足不同场景需求。
• 安全可靠：提供只读访问、输入验证和错误处理等安全特性，确保数据安全。

📦 安装指南

如快速开始部分所述，需先安装uv：

curl -LsSf https://astral.sh/uv/install.sh | sh

然后可使用uvx运行opengenes - mcp服务器。

💻 使用示例

基础用法

以下是OpenGenes MCP服务器与AI助手实际协作的示例：


此示例展示了如何通过AI助手使用自然语言查询OpenGenes数据库，该查询通过MCP服务器转换为SQL查询。你可以在聊天界面中使用此数据库进行研究问题查询，也可在基于AI的开发工具（如Cursor、Windsurf、带有Copilot的VS Code）中使用，在编码时直接访问衰老和长寿研究数据，显著提高生物信息学工作效率。

高级用法

如果你想更深入了解Model Context Protocol是什么以及如何更高效地使用它，你可以参加[DeepLearning AI课程](https://www.deeplearning.ai/short - courses/mcp - build - rich - context - ai - apps - with - anthropic/)或在YouTube上搜索MCP相关视频。

📚 详细文档

数据源和更新

OpenGenes MCP服务器自动从Hugging Face Hub上的[longevity - genie/bio - mcp - data](https://huggingface.co/longevity - genie/bio - mcp - data)仓库下载数据，确保：

• 始终保持最新：自动访问最新的OpenGenes数据库，无需手动更新。
• 可靠分发：集中式数据托管，支持版本控制和变更跟踪。
• 高效缓存：下载的文件会在本地缓存，以减少网络请求。
• 离线支持：支持本地备用文件，用于开发和离线使用。

数据文件存储在Hugging Face仓库的opengenes子文件夹中，包括：

• open_genes.sqlite - 完整的OpenGenes数据库
• prompt.txt - 数据库模式文档和使用指南

可用工具

该服务器提供了三个主要工具，用于与OpenGenes数据库进行交互：

1. opengenes_db_query(sql: str) - 对OpenGenes数据库执行只读SQL查询
2. opengenes_get_schema_info() - 获取详细的模式信息，包括表、列和枚举
3. opengenes_example_queries() - 获取带有描述的示例SQL查询列表

可用资源

1. resource://db - prompt - 完整的数据库模式文档和使用指南
2. resource://schema - summary - 表格及其用途的格式化摘要

数据库模式

示例查询

-- 获取进行最多寿命实验的前10个基因
SELECT HGNC, COUNT(*) as experiment_count 
FROM lifespan_change 
WHERE HGNC IS NOT NULL 
GROUP BY HGNC 
ORDER BY experiment_count DESC 
LIMIT 10;

-- 查找在小鼠中延长寿命的基因
SELECT DISTINCT HGNC, effect_on_lifespan 
FROM lifespan_change 
WHERE model_organism = 'mouse' 
AND effect_on_lifespan = 'increases lifespan' 
AND HGNC IS NOT NULL;

-- 获取与基因相关的衰老标志
SELECT HGNC, "hallmarks of aging" 
FROM gene_hallmarks 
WHERE "hallmarks of aging" LIKE '%mitochondrial%';

-- 按种族查找与长寿相关的基因
SELECT HGNC, "polymorphism type", "nucleotide substitution", ethnicity 
FROM longevity_associations 
WHERE ethnicity LIKE '%Italian%';

-- 查找同时具有寿命影响和长寿关联的基因
SELECT DISTINCT lc.HGNC 
FROM lifespan_change lc 
INNER JOIN longevity_associations la ON lc.HGNC = la.HGNC 
WHERE lc.HGNC IS NOT NULL;

安全特性

• 只读访问：仅允许SELECT查询
• 输入验证：阻止INSERT、UPDATE、DELETE、DROP、CREATE、ALTER、TRUNCATE操作
• 错误处理：提供全面的错误处理和信息丰富的错误消息

测试与验证

MCP服务器提供了全面的测试，包括使用LLM作为评判的测试，用于评估对复杂查询的响应质量。但为节省成本，基于LLM的测试在CI中默认禁用。

环境设置

如果你想运行使用Gemini模型的MCP函数的LLM代理测试，需要在项目根目录创建一个.env文件，并设置你的Gemini API密钥：

echo "GEMINI_API_KEY=your - gemini - api - key - here" > .env

注意：.env文件和Gemini API密钥仅在运行LLM代理测试时需要。所有其他测试和基本MCP服务器功能无需任何API密钥即可工作。

运行测试

运行MCP服务器的测试：

uv run pytest -vvv -s

你也可以运行手动测试：

uv run python test/manual_test_questions.py

你可以像使用uvx一样，将MCP Inspector与本地构建的MCP服务器一起使用。

可探索的研究问题

🔧 技术细节

MCP是一种协议，它弥合了AI系统与专业领域知识之间的差距，具有以下特点：

• 结构化访问：直接连接到权威的衰老和长寿研究数据
• 自然语言查询：通过SQL简化与专业数据库的交互
• 类型安全：通过FastMCP实现强类型和验证
• AI集成：与AI助手和代理无缝集成

📄 许可证

本项目采用MIT许可证。

致谢

• [OpenGenes数据库](https://open - genes.com/)提供了全面的衰老研究数据
  • 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.
• Model Context Protocol提供了协议规范
• FastMCP提供了MCP服务器框架

本项目是[Longevity Genie](https://github.com/longevity - genie)组织的一部分，该组织开发用于健康、遗传学和长寿研究的开源AI助手和库。

Longevity Genie的其他MCP服务器

我们还为生物医学研究开发了其他专业MCP服务器：

• [biothings - mcp](https://github.com/longevity - genie/biothings - mcp) - 用于BioThings.io API的MCP服务器，提供对基因注释（mygene.info）、变异注释（myvariant.info）和化合物数据（mychem.info）的访问

我们得到了以下机构的支持：


HEALES - 健康寿命延长协会

和

[](https://ibima.med.uni - rostock.de/)

[IBIMA - 医学与衰老研究生物统计学与信息学研究所](https://ibima.med.uni - rostock.de/)

🤝 贡献

我们欢迎社区的贡献！无论你是研究人员、开发者还是对衰老和长寿研究感兴趣的爱好者，都有多种方式参与其中：

贡献方式

• 🐛 报告Bug：发现问题？请在GitHub上创建一个详细的issue。
• 💡 提出功能请求：有新功能的想法？我们很乐意听取！
• 📝 完善文档：帮助改进我们的文档、示例或教程。
• 🧪 参与测试：添加测试用例，特别是针对边缘情况或新查询模式的测试。
• 🔍 保障数据质量：帮助识别和报告数据不一致问题或提出改进建议。
• 🚀 优化性能：优化查询、改进缓存或提升服务器性能。
• 🌐 拓展集成：为新的MCP客户端或AI系统创建示例。
• 🎥 制作教程和视频：创建教程、视频指南或教育内容，展示如何使用MCP服务器。
• 📖 分享用户故事：分享你使用我们MCP服务器的研究工作流程和成功故事。
• 🤝 促进社区推广：帮助我们在生物信息学社区推广MCP的应用。

开始贡献

1. Fork仓库
2. 创建一个功能分支 (git checkout -b feature/amazing - feature)
3. 进行更改并添加测试
4. 运行测试套件 (uv run pytest)
5. 提交更改 (git commit -m 'Add amazing feature')
6. 将更改推送到你的分支 (git push origin feature/amazing - feature)
7. 打开一个Pull Request

开发指南

• 遵循现有的代码风格（我们使用black进行格式化）
• 为新功能添加测试
• 根据需要更新文档
• 保持提交内容聚焦，并编写清晰的提交消息

交流讨论

如有问题或想法，请随时创建一个issue进行讨论！我们很友好，总是乐意帮助新手入门。你的贡献有助于推动开放科学和长寿研究的发展。

⚠️ 已知问题

数据库覆盖范围

目前，此MCP服务器仅使用了完整OpenGenes数据库的一部分。完整的OpenGenes数据库包含更多的表和数据，尚未包含在我们的MCP实现中。我们需要贡献者帮助扩展对完整数据库的支持！ 如果你有兴趣帮助扩展数据库覆盖范围，请参阅我们的贡献部分。

测试覆盖范围

虽然我们提供了全面的测试，包括使用LLM作为评判的评估，但并非所有测试用例都已针对实际的OpenGenes Web界面进行了手动验证。一些自动化测试结果可能需要手动验证以确保准确性。欢迎贡献者帮助提高测试覆盖范围和验证质量。