biothings-mcp

biothings-mcp

用于 Biothings.io 的 MCP（Model Context Protocol）服务

此服务为 BioThings 实现了 Model Context Protocol（MCP），提供用于访问和操作生物医学数据的标准化接口。MCP 使 AI 助手和 Agent 能够通过连接权威数据源的结构化接口访问专业生物医学知识。支持的 BioThings 数据源包括：

• mygene.info — 基因注释和查询服务
• myvariant.info — 变异注释和查询服务
• mychem.info — 化合物注释和查询服务

如果你想进一步了解 Model Context Protocol 以及如何更高效地使用它，可以学习 DeepLearning AI 课程，也可以直接在 YouTube 上搜索 MCP 视频。

关于 MCP（Model Context Protocol）

MCP 是一种连接 AI 系统与专业领域知识的协议。它支持：

• 结构化访问：直接连接权威生物医学数据源
• 自然语言查询：简化与专业数据库的交互
• 类型安全：通过 biothings-typed-client 实现强类型和验证
• AI 集成：与 AI 助手和 Agent 无缝集成

可用的 API 接口

此服务利用 biothings-typed-client 库，为不同的 BioThings 数据类型提供专用 API 接口。这些接口通过以下工具处理程序实现：

• 基因接口：GeneTools（封装 GeneClientAsync）
• 变异接口：VariantTools（封装 VariantClientAsync）
• 化学品接口：ChemTools（封装 ChemClientAsync）
• 分类群接口：TaxonTools（封装 TaxonClientAsync）
• 下载接口：DownloadTools（提供文件下载和序列分析功能）

本地文件保存功能

此服务通过 DownloadTools 接口提供本地文件保存功能，包括：

下载工具

• download_entrez_data：从 NCBI Entrez 数据库下载数据（以字符串形式返回内容）
• download_entrez_data_local：从 NCBI Entrez 数据库下载数据并保存到本地文件

输出目录管理

• 默认位置：文件保存到当前工作目录中的 biothings_output/ 目录
• 自定义位置：使用 --output-dir 参数指定自定义输出目录
• 自动创建：如果输出目录不存在，将自动创建
• 唯一文件名：自动生成的文件名包含 UUID 前缀，以避免冲突

支持的文件格式

• FASTA：序列数据使用 .fasta 扩展名
• GenBank：GenBank 格式数据使用 .gb 扩展名
• 比对：比对结果使用 .aln 扩展名
• JSON：结构化数据使用 .json 扩展名
• 文本：一般文本数据使用 .txt 扩展名

快速开始

安装 uv

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

# Verify installation
uv --version
uvx --version

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

使用 uvx 运行

无需克隆代码仓库，即可使用 uvx 直接运行 biothings-mcp 服务：

STDIO 模式（适用于需要 stdio 的 MCP 客户端，也可用于保存文件）

# Run the server in STDIO mode (default mode)
uvx biothings-mcp

# Or explicitly specify stdio mode
uvx --from biothings-mcp stdio

# With custom output directory
uvx --from biothings-mcp stdio --output-dir ./my_data

HTTP Streamable 模式（Web 服务）

# Run the server in streamable HTTP mode on default port (3001)
uvx --from biothings-mcp server run

# Run on a custom port
uvx --from biothings-mcp server run --port 8000

# Run on custom host and port
uvx --from biothings-mcp server run --host 0.0.0.0 --port 8000

# With custom output directory
uvx --from biothings-mcp server run --output-dir ./my_data

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

# Run the server in SSE mode on default port (3001)
uvx --from biothings-mcp sse

# Run on a custom port
uvx --from biothings-mcp sse --port 8000

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

配置你的（Anthropic Claude Desktop、Cursor、Windsurf 等）

我们提供使用代理的 stdio 配置（可能需要通过 npx 运行）：

• mcp-config-remote.json - 远程配置
• mcp-config-stdio.json - 适用于不支持的 MCP 客户端的 localhost stdio 配置

检查 Biothings MCP 服务

如果你想检查 MCP 提供的方法，请使用 npx（可能需要安装 nodejs 和 npm）

使用 MCP Inspector 测试 MCP 设置。

如果你想检查本地 streamable-http 服务，请使用：

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

为远程服务添加 -remote 后缀。

如果你想检查本地 stdio 服务，请使用：

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

你也可以手动运行 inspector，并在界面中填写服务参数：

npx @modelcontextprotocol/inspector

之后，你可以通过 MCP Inspector 在 http://127.0.0.1:6274 探索其方法

仓库设置

# Clone the repository
git clone https://github.com/longevity-genie/biothings-mcp.git
cd biothings-mcp
uv sync

运行 MCP 服务

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

# Start the MCP server in HTTP streamable mode (default port 3001)
uv run server run

# Run in STDIO mode
uv run stdio

# Run in SSE mode
uv run sse

# Run with custom port
uv run server run --port 8000

# Run with custom output directory
uv run server run --output-dir ./my_data

与 AI 系统集成

若要将此服务集成到兼容 MCP 的 AI 客户端，可以使用此仓库中提供的预配置 JSON 文件之一：

• 连接到本地运行的服务： 使用 mcp-config.json。请先确保服务正在运行，可以通过 uv run server（参见运行 MCP 服务）或 docker-compose up（参见 Docker 部署）启动。
• 连接到公开托管的服务： 使用 mcp-config-remote.json。此配置会连接到 https://biothings.longevity-genie.info/mcp，无需在本地运行任何内容。

只需将 AI 客户端（例如 Cursor、Windserve、ClaudeDesktop、带 Copilot 的 VS Code，或其他客户端）指向相应的配置文件即可。

以下示例展示了配置后，这些工具在 Cursor 这类 MCP 客户端中的显示效果：

已知问题

该库目前处于 Beta 质量阶段。当前的主要问题是，大模型通常不够智能，不知道如何提供有效的基因和基因变体符号。我们计划通过扩展注释并提供额外的实体解析方法来缓解此问题。

测试与验证

运行 API 端点测试：

uv run pytest -vvv -s

你可以像使用 uvx 一样，使用本地构建的 MCP 服务搭配 MCP inspector

注：使用 MCP Inspector 是可选的。配置完成后，大多数 MCP 客户端（如 Cursor、Windsurv 等）会自动显示此服务提供的工具。不过，Inspector 可用于详细测试和探索。

如果你选择通过 npx 使用 Inspector，请确保已安装 Node.js 和 npm。建议使用 nvm（Node 版本管理器）来管理 Node.js 版本。

这会打开一个 Web 界面，你可以在其中探索和测试所有可用工具。

文档

有关 MCP 协议及其实现的详细文档，请参阅：

• MCP 协议文档
• biothings-typed-client 文档
• FastAPI-MCP 文档

许可证

本项目采用 MIT 许可证。

致谢

• 感谢 BioThings 提供 REST API 和原始的客户端库

• 感谢 MCP Protocol 提供协议规范

• 感谢 Pydantic 提供数据验证框架

• 感谢 FastAPI-MCP 提供 MCP 服务实现

• 本项目隶属于 Longevity Genie 组织。该组织致力于开发用于健康、遗传学和长寿研究的开源 AI 助手和库。

我们的支持者：

HEALES - 健康长寿协会

以及

IBIMA - 医学生物统计与信息学及衰老研究所