内容
ensembl-m一个适用于 [Ens GraphQL API](https://beta.ensembl.org/core) 的 [MCP](https://model.io) 服务器，基于 [FastMCP](https://gofastmcp.com) 构建。
- 通过 **stdio** 和 **可流式 HTTP** 运行。
- 每个数据工具都**支持后台任务**（MCP SEP-1686 viaCP 的 `Task，默认进程内 `memory://`后端 - 无需 Redis/Docker）。
- 配备一个 **Typer CLI** 来提供服务器并运行实时示例。
- 包括 **Agno语言代理**，集成测试和手动查询## 安装
### 1. 通过 PyPI）
您可以使用 `uvx` 直接运行 MCP 服务器，而无需克隆存储库：bash
uvx ensembl-mcp serve
```
### 2. 从源码（用于开发）
在本地克隆此存储库并运行：
```bash
uv sync
```
需要 Python 3.14+。
对于代理测试和自然语言 CLI 入口点，请安装开发依赖项：
```bash
uv sync --dev
```
## 连接到 LLM 客户端和代理
要将此 MCP 服务器与您喜欢的 AI 工具（例如 Claude Desktop、Cursor、Claude Code、Cline 等）一起使用，您需要将它们配置为通过 **stdio** 运行服务器。
### 方法 A：使用 `uvx`（推荐）
由于该软件包已发布到 PyPI，您可以直接配置您的客户端而无需克隆存储库：
#### 1. Claude Desktop
将以下内容添加到您的 `claude_desktop_config.json` 中：
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
* **Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"ensembl": {
"command": "uvx",
"args": [
"ensembl-mcp",
"serve"
]
}
}
}
```
#### 2. Cursor IDE
在设置中添加一个新的 MCP 服务器：
1. 打开 **Cursor 设置**（齿轮图标或 `Ctrl+,` / `Cmd+,2. 导航到 **功能** -> **M。
3. 点击 **+ 添加新的 MCP 服务器**。
4. 填写字段：
* **名称**:`
* **类型**: `command`
* **命令**: `uvx ensembl-mcp serve`
5. 点击 **保存**。
#### 3. Claude Code
对于 Claude CLI 开发人员代理（`claudecode`），您可以通过运行以下命令添加此服务器：
```bash
claude mcp add ensembl uvx ensembl-mcp serve
```
#### 4. Cline / Roo Code（VS Code
如果您使用 VS Code 扩展，如 **C 或 **Roo Code**，请编辑您的本地 MCP 设置文件（通常可以通过 MCP 设置选项卡访问）：
```json
{
"mcpServers": {
"ensembl": {
"command": "uvx",
"args": [
"ensembl-mcp",
"serve"
]
}
}
}
```
---
### 方法 B：从源码运行（用于开发）
如果您更喜欢从本地克隆运行，请按如下方式配置您的客户端：
#### 1. Claude Desktop
将以下内容添加到您的 `claude_desktop_config.json` 中：
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude.json`
* **Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"ens {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/ensembl-mcp",
" "ensembl-mcp",
"serve"
]
}
}
}
```
> **注意：** 将 `/absolute/path/to/ensembl-mcp` 替换为克隆存储库的实际路径。
#### 2. Cursor IDE
您可以在 Cursor 设置 UI 中直接添加此 MCP 服务器：
1. 设置**（齿轮图标或 `Ctrl+, `Cmd+,`）。
导航到 ** -> **MCP. 点击 **+ 添加新的 MCP 服务器**。
4. 填写字段：
**名称**:embl`
* **: `command`
**命令**:
bash
uv --absolute/path/to/ensembl-mcp" run-mcp serve
```
5. 点击 **保存 3.
对于 Claude CLI代理（`claude），您可以通过运行添加此服务器：
```bash
claude add ensembl uv --directory "/absolute/path/to/ensembl-mcp" run ensembl-mcp serve
```
#### 4. Cline / Roo Code（VS Code 扩展）
如果您使用 VS Code 扩展，如 **Cline** 或 **Roo Code**，请编辑您的本地 MCP 设置文件：
```json
{
"mcpServers": {
"ensembl": {
"command": "uv",
args": [
"--directory",
"/absoluteensembl-mcp",
"run",
embl-mcp",
"serve"
]
}
}
}
```
---
### 自定义配置（环境变量）
如果您需要配置或自定义行为（例如设置默认基因组或 API 端点），可以在客户端配置中传递环境变量。
例如，在 **Claude Desktop** 或 **Cline** 中：
```json "mcpServers": {
"": {
"command": "uvx",
"args": [
"ensembl-mcp",
"serve"
],
"env": {
"ENSEMBL_MCP_REQUEST_TIMEOUT": "120"
}
}
}
}
```
有关所有可用的环境变量，请参见下面的 [配置](#配置)。
## 运行服务器
### 通过 PyPI（推荐）
```bash
# stdio（默认）- 用于 Claude Desktop、CLI 客户端等
uvx ensembl-mcp serve
# 可流式 HTTP - 端点在 http://<host>:<port>/mcp
uvx ensembl-mcp serve --transport http --host 0.0.0. 8000
```
### 从源码（用于开发）
```bash
# stdio（默认）- 用于 Claude Desktop、CLI 客户端等
uv run ensembl-mcp serve
# 可流式 HTTP - 端点在 http://<host>:<port>/mcp
uv run ensembl-mcp serve --transport http --host 0.0.0.0 --port 8000
```
## 工具 工具 | 描述 |
| --- | --- `get_version` | Ensembl GraphQL API 版本。 |
| `find_genes_by_symbol` | 按显示符号查找基因（例如 `BRCA2`）。 |
| `get_gene_by_id` | 按 Ensembl 稳定 ID 查找基因。 |
| `get_transcript` | 按稳定 ID 或符号查找转录本。 |
| `transcript_search` | 跨基因组的全文本转录本搜索。 |
| `get_product_by_id` | 按稳定 ID 查找蛋白质产品。 |
| `get_region` | 按名称查找区域（例如染色体）。 |
| `overlap_region` | 基因/转录本重叠基因组区间。 |
| `find_genomes` | 将物种/组装关键词解析为基因组（s）+ `genome_id`。 |
| `get_genome` | 按 `genome_id` 获取基因组元数据。 |
| `get_sequence` | 按摘要 ID 获取原始 Refget 序列或子序列。 |
| `get_sequence_to_file` | 将 Refget 序列或子序列流式写入本地文本文件。 |
| `get_sequence_metadata` | 获取序列摘要 ID 的 Refget 元数据和别名。 |
| `graphql_query` | 运行任意原始 GraphQL 查询。 |
| `graphql_query_to_file` | 运行任意原始 GraphQL 查询并将 JSON 结果写入文件。 |
| `bulk_find_genes` | 一次解析多个符号（后台任务展示，具有进度）。 |
大多数查找接受 `genome_id`（UUID）；默认为人类参考 `a7335667-93e7-11ec-a39d-005056b38ce3`。使用 `find_genomes` 获取其他物种。
## CLI 示例（实时）
### 通过 PyPI（推荐）
```bash
uvx --from ensembl-mcp ensembl-mcp examples version
uvx --from ensembl-mcp ensembl-mcp examples gene BRCA2
uvx --from-mcp ensembl-mcp examples genome --scientificHomo sapiens"
uvx --from ensembl-mcp ensembl-mcp examples overlap 13 32315086 32400268
uvx --from ensembl-mcp ensembl-mcp examples bulk BRCA2 TP53 EGFR
uvx --from ensembl-mcp ensembl-mcp examples sequence 6aef897c3d6ff78aff06ac189178dd --start 0 --end 20
uvx --from ensembl-mcp ensembl-mcp examples sequence 6a3d678aff06ac189178dd --start 0 --end 20 --output-name refget_sequenceuvx --from ensembl-mcp ensembl sequence-metadata 6aef897c3d6ff0c78aff06ac189178uvx --from ensembl-mcp ensembl examples raw '{ version { api { major minor patch }'
uvx --from ensembl-mcp-mcp examples raw '{ version { api { major minor patch } } }' --output-name version.json
```
### 从源码（用于开发）
```bash
uv run ensembl-mcp examples version
uv run ensembl-mcp examples gene BRCA2
uv run ensembl-mcp examples genome --scientific-name "Homo sapiens"
uv run ensembl-mcp examples overlap 32315086 32400268
ensembl-mcp examples bulk BRCA2 EGFR
uv run ensembl-mcp examples sequence 6aef897c3d6ff0c78aff06ac189178dd --start --end 20
uv run ensembl examples sequence 6aef897c3d6ff0c78aff06ac189178dd --start 0 --end 20 --output-name refget_sequence.txt
uv run ensembl-mcp examples sequence-metadata 6aef897c3d6ff0c78aff06ac189178dd
uv run ensembl examples raw '{ version { api { major minor patch } } }'
uv run ensembl-mcp examples raw '{ version { api { major minor patch } } }' --output-name version.json
```
## 自然语言代理
可选的 Agno 代理允许您从 CLI 提出自然语言问题。
### 通过 PyPI（推荐）
```bash
# 确保在环境中设置 GEMINI_API_KEY、GOOGLE_API_KEY 或 ENSEMBL_MCP_AGENT_API_KEY
uvx ensembl-mcp ensembl-mcp agent "您的 Ensembl 自然语言问题"
```
### 从源码（用于开发）
其入口点是：
```bash
uv run ensembl-mcp agent "您的 Ensembl 自然语言问题"
```
内部并调用与 MCP 工具相同的实时 Ens，然后总结结果。首先安装开发依赖项，因为 Agno 和模型提供程序是开发依赖项：
```bash
uv sync --dev
```
在 `.env` 中配置模型密钥。对于 OpenAI 兼容的模型：
```bash
ENSEMBL_MCP_AGENT_API_KEY=
ENSEMBL_MCP_AGENT_MODEL_ID=gpt-4o-mini
```
对于 Gemini 模型：
```bash
ENSEMBL_MCP_AGENT=gemini-flash-latest
GEMINI_API_KEY=
# 或 GOOGLE_API_KEY=
```
然后提问：
#### 通过 PyPI（推荐）
```bash
uvx --from ensembl-mcp ensembl-mcp agent "哪个人类染色体包含 BRCA2？"
uvx --from ensembl-mcp ensembl-mcp agent "查找人类中 TP53 的 Ensembl 稳定 ID。"
uvx --from ensembl-mcp ensembl-mcp agent "哪些基因重叠人类染色体 13:32315086-32400268？"
uvx --embl-mcp ensembl-mcp agent "在人类中，我指的是肿瘤蛋白 p53 基因。给我它的 HGNC 符号、Ensembl 基因稳定 ID 和染色体。不要讨论变体。"
uvx --from ensembl-mcp ensembl agent "ENSP00000369497.3 是一个 Ensembl 产品稳定 ID。它是什么产品类型，长度是多少#### 从源码（用于开发）
```bash
uv run ensembl-mcp agent "哪个人类染色体包含 BRCA2？"
uv run ensembl-mcp agent "查找人类中 TP53 的 Ensembl 稳定 ID。"
uv run ensembl-mcp agent "哪些基因重叠人类染色体 13:32315086-32400268？"
uv run-mcp agent "在人类中肿瘤蛋白 p53 基因。给我它的 HGNC 符号、Ensembl 基因稳定 ID 和染色体。不要讨论变体。"
uv run ensembl-mcp agent "ENSP00000369497.3 是一个 Ensembl 产品稳定 ID。它是什么产品类型，长度是多少？"
```
使用 `--model` 覆盖 `ENSEMBL_MCP_AGENT_MODEL_ID` 以运行一次：
```# 通过 PyPI
uvx --from ensembl-mcp ensembl-mcp agent --model gemini-flash-latest "哪个人类染色体包含 BRCA2？"
# 从源码
uv run ensembl-mcp agent --model gemash-latest "哪个人类染色 BRCA2？"
```
## 大型和原始有效载荷
大多数 GraphQL 支持的 MCP 工具返回紧凑的元数据：标识符、符号、区域坐标、转录本计数、产品长度和基因组元数据。当前的 Ensembl beta core GraphQL 模式在某些对象上具有 `sequence` 字段，但 GraphQL `Sequence` 类型当前公开元数据，如 `alphabet` 和 `checksum`，而不是原始核苷酸或氨基酸字符串。
原始序列检索由 GA4GH Refget API 处理。对于短切片，`get_sequence` 或 `examples sequence` 可以直接返回序列字符串。对于较大范围或整个序列，请使用文件写入入口点：
```bash
uv run ensembl-mcp examples sequence 6aef897c3d6ff0c78aff06ac189178dd --output-name refget_sequence.txt
```
MCP 工具等效项是 `get_sequence_to_file`。它将 Refget 响应流式写入磁盘下的 `ENSEMBL_MCP_OUTPUT_DIR`，并仅返回路径、字节大小、序列请求的范围。
对于可能返回大型 JSON 有效载荷的原始 GraphQL 查询，请使用 GraphQL 文件写入入口点：
```bash
uv run ensembl-mcp examples raw '{ version { api { major minor patch } } }' --output-name version.json
```
MCP 效项graphql_query_to_file`。它写入 `ENSEMBL_MCP_OUTPUT_DIR` 下并仅返回本地路径大小和顶级 JSON 键。`output_name` 必须是文件名，而不是路径。
##通过 `ENSEMBL_MCP_*` 环境变量或 `.env` 文件设置。项目使用 `load_dotenv()` 显式加载 `.env`，然后 pyd 读取配置。使用.template` 作为支持的本地值的列表。
| 变量 | 默认 描述 |
| --- | --- `ENSEMBL_MCP_ENDPOINT` | `https://beta..org/data/graphql | GraphQL。 |
| `L_MCP_ENDPOINT` |://beta..org/data/refget 用于序列检索get 端点。 |
| `ENSEMBL_MCP_REQUEST_TIMEOUT` | `60` 超时（ |
| `ENSEMBL_MCP_GENOME_ID `a73356693e7ec-a39005056b38ce3` | 默认基因组 ID。 |
ENSEMBL_MCP_OUTPUT_DIR`ensembl_m` | 用于文件的目录，如_sequence_to_file `graphql_query`。 |
ENSEMBL_AGENT_API_KEY`设置 | 可 Agno 代理的 API 密钥。 |
| `ENSE_MCP_AGENT_MODEL_ID` | `gpto-mini`no 代理。`...` ID 使用适配器。 `ENSEMBCP_AGENT_BASE_URL` | 未设置 | 可选的 OpenAI 兼容基准 URL。 |
| `ENSEMBL_MCP_AGENT_TIMEOUT` | `120` | LLM 调用超时（秒）。 |
| `GEMINI_API_KEY` | 未设置 | `gemini...` 代理模型的 Gemini API 密钥备用。 |
| `GOOGLE_API_KEY` | 未设置gemini...`模型的 Google API。 |
后台任务 `FASTMOCKET_URL` 配置 `memory://`redis://...多工作器。
## 测试
集成测试会命中实时，如果离线优雅地：
```bash run pytest
```
Agno 自然语言集成测试还需要 `ENSEMBL_MCP_AGENT_API_KEY`；如果没有它，测试将被跳过。
## 范围
当前的 Ensembl beta `data/graphql` 网关仅提供核心模式（基因、转录本、产品、区域、基因组）。它**不**提供按rsid或坐标的变异解析 - 这属于单独的`ensembl-hypsipyle`变异服务，该服务无法从此网关访问。因此，变异在此范围之外。
有关模块化客户端架构、GA4GH Refget集成以及Refget与变异表示标准之间关系的更多开发人员详细信息，请参见[架构和Refget集成](docs/refget_and_architecture.md)指南。
