Opengenes Mcp

搜索 Python

🚀 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

其他uvx模式（STDIO、HTTP、SSE）

STDIO模式（适用于需要标准输入输出的MCP客户端，保存文件时可能有用）

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

HTTP模式（Web服务器）

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

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

SSE模式（服务器发送事件）

# 以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服务器

使用MCP Inspector探索服务器功能

若要检查MCP服务器提供的方法，请使用npx（你可能需要安装nodejs和npm）：

对于使用uvx的STDIO模式：

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

对于HTTP模式（确保服务器先运行）：

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

之后，你可以在http://127.0.0.1:6274 使用MCP 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助手实际协作的示例：

![OpenGenes MCP使用示例](images/open - genes - usage - chat.png)

此示例展示了如何通过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数据库进行交互：

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

可用资源

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

数据库模式

详细的模式信息

主表

lifespan_change（47列）：跨模式生物的实验寿命数据，包含干预细节
gene_criteria（2列）：按衰老标准对基因进行分类（12个不同类别）
gene_hallmarks（2列）：与基因相关的衰老标志
longevity_associations（11列）：来自人类研究的与长寿相关的群体遗传学数据

关键字段

HGNC：基因符号（所有表的主要标识符）
model_organism：研究生物（小鼠、秀丽隐杆线虫、果蝇等）
effect_on_lifespan：寿命变化方向（增加/减少/无变化）
intervention_method：基因干预方法（敲除、过表达等）
criteria：与衰老相关的基因分类（12个类别）
hallmarks of aging：与基因相关的生物衰老过程

示例查询

常见研究问题的示例SQL查询

-- 获取进行最多寿命实验的前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服务器探索的研究问题

哪些基因干预最能延长小鼠寿命？
哪些基因敲除对模式动物的寿命延长效果最显著？
GHR基因敲除小鼠的哪些生理过程得到了改善？
哪种基因干预使果蝇的寿命延长最多？
过表达VEGFA基因的小鼠寿命延长了多少？
是否有针对小鼠肝脏的干预措施可以延长其寿命？
哪种基因与长寿的关联得到了最多研究的证实？
FOXO3基因的哪些多态性与人类长寿相关？
APOE基因与长寿的关联在哪些种族群体中得到了证实？
INS基因多态性是否与长寿有关？
哪些基因与转录改变相关？
KL基因与哪些衰老标志相关？
有多少基因与人类长寿相关？
对IGF1R基因进行了哪些类型的研究？
你知道哪些关于PTEN基因与衰老之间联系的证据？
哪些基因既与长寿相关，又在老年人中表达改变？
人类ACE2基因的表达是否随年龄增长而改变？
在线虫中，哪些基因需要下调以延长其寿命？

🔧 技术细节

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://github.com/longevity - genie/biothings - mcp/raw/main/images/heales.jpg)

HEALES - 健康寿命延长协会

和

[![IBIMA](https://github.com/longevity - genie/biothings - mcp/raw/main/images/IBIMA.jpg)](https://ibima.med.uni - rostock.de/)

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

🤝 贡献

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

贡献方式

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

开始贡献

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

开发指南

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

交流讨论

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

⚠️ 已知问题

数据库覆盖范围

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

测试覆盖范围

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

0 条评论
分类：搜索