Ensembl MCP Server

🚀 🧬 Ensembl API MCP 服务器

这是一个功能全面的模型上下文协议（MCP）服务器，它公开了 Ensembl 的 REST API。该服务器使用 TypeScript MCP SDK 构建。

• 覆盖全面：10 个工具对应不同功能区域，而非 100 多个单独的端点，但仍能公开几乎整个 API。
• 可用于生产环境：全程使用 TypeScript，具备强大的错误处理能力和简洁的 API 客户端层。
• 对生物学家友好：按生物任务（基因、变异、比较……）分组，而非按底层 REST 路径分组。

平台展示：

• Smithery
• Glama

🚀 快速开始

本服务器提供了一系列工具，可用于获取基因信息、搜索基因、检索序列等。以下是一些常见的使用场景：

• 🧬 基因信息：通过 ID 或符号获取详细信息
• 🔍 基因搜索：扫描任何物种的基因
• 🧬 序列检索：提取任何基因组区域的 DNA
• 🔬 变异数据：探索变异及其注释
• 📊 转录本信息：检查转录本和异构体
• 🌍 多物种支持：涵盖 Ensembl 中的所有物种
• 🔗 交叉引用：一键跳转到外部数据库
• ⚡ 速率限制：内置限流功能，确保在 Ensembl 限制范围内使用

✨ 主要特性

• 功能覆盖全面：通过 10 个工具映射功能区域，覆盖了几乎整个 Ensembl REST API。
• 生产就绪：采用 TypeScript 构建，具备强大的错误处理和清晰的 API 客户端层。
• 生物友好设计：按生物任务分组，方便生物学家使用。

📦 安装指南

你可以选择以下首选的安装方法：

选项 1：通过 Smithery 安装

1. 访问 Smithery - Ensembl MCP 服务器。以下是一些常见平台的安装命令：

# claude:
npx -y @smithery/cli@latest install @effieklimi/ensembl-mcp-server --client claude --key your-smithery-secret-key

# cursor:
npx -y @smithery/cli@latest install @effieklimi/ensembl-mcp-server --client cursor --key your-smithery-secret-key

# vscode:
npx -y @smithery/cli@latest install @effieklimi/ensembl-mcp-server --client vscode --key your-smithery-secret-key

# windsurf:
npx -y @smithery/cli@latest install @effieklimi/ensembl-mcp-server --client windsurf --key your-smithery-secret-key

你可以查看 MCP 的 Smithery 链接以获取更多平台选项。

选项 2：本地开发设置

对于开发或自定义设置：

1. 克隆并安装依赖项：

git clone https://github.com/effieklimi/ensembl-mcp-server.git
cd ensembl-mcp-server
npm install

2. 手动配置 Claude Desktop： 编辑配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

添加以下服务器配置：

{
    "mcpServers": {
        "ensembl": {
            "command": "npm",
            "args": ["run", "start"],
            "cwd": "/absolute/path/to/ensembl-mcp-server"
        }
    }
}

3. 重启 Claude Desktop：Ensembl 工具将出现在可用工具列表中。

开发设置

# 热重载开发
npm run dev

# 运行测试
npm test

# 生产构建（可选）
npm run build
npm run start:prod

📚 详细文档

十个工具（带端点）

1 · ensembl_feature_overlap

查找与某个区域或另一个特征重叠的基因、转录本或调控元件。

GET /overlap/region/:species/:region
GET /overlap/id/:id

典型查询：“哪些基因位于 17 号染色体的 43 - 44 Mb 区域？” – “与 BRCA1 重叠的有哪些？”

2 · ensembl_regulatory

调控特征、结合矩阵及相关注释。

GET /overlap/region/:species/:region             (with regulatory filters)
GET /overlap/translation/:id                     (regulatory features on proteins)
GET /species/:species/binding_matrix/:binding_matrix_stable_id

使用场景：转录因子结合位点、调控注释。

3 · ensembl_protein_features

蛋白质水平的结构域和功能位点。

GET /overlap/translation/:id

使用场景：蛋白质结构域、信号肽、催化残基。

4 · ensembl_meta

服务器元数据、物种列表、版本信息和诊断信息。

GET /info/ping
GET /info/rest
GET /info/software
GET /info/data
GET /info/species
GET /info/divisions
GET /info/assembly/:species
GET /info/biotypes/:species
GET /info/analysis/:species
GET /info/external_dbs/:species
GET /info/variation/:species
GET /archive/id/:id
POST /archive/id

典型查询：“人类有哪些组装版本？” – 服务器健康检查。

5 · ensembl_lookup

转换 ID 与符号，获取交叉引用，重新编码变异。

GET  /lookup/id/:id
GET  /lookup/symbol/:species/:symbol
POST /lookup/id
POST /lookup/symbol
GET  /xrefs/id/:id
GET  /xrefs/symbol/:species/:symbol
GET  /xrefs/name/:species/:name
GET  /variant_recoder/:species/:id
POST /variant_recoder/:species

使用场景：“BRCA1 的 Ensembl ID 是什么？” – 交叉引用 UniProt。

6 · ensembl_sequence

检索 DNA、RNA 或蛋白质序列。

GET  /sequence/id/:id
GET  /sequence/region/:species/:region
POST /sequence/id
POST /sequence/region

使用场景：基因 FASTA 序列、转录本 cDNA、基因组区域。

7 · ensembl_mapping

坐标转换（基因组 ↔ cDNA/CDS/蛋白质）和组装提升。

GET /map/cdna/:id/:region
GET /map/cds/:id/:region
GET /map/translation/:id/:region
GET /map/:species/:asm_one/:region/:asm_two

使用场景：将 CDS 映射到 GRCh38，将蛋白质坐标转换为基因组坐标。

8 · ensembl_compara

比较基因组学 — 同源性、基因树、比对。

GET /homology/id/:species/:id
GET /homology/symbol/:species/:symbol
GET /genetree/id/:id
GET /genetree/member/symbol/:species/:symbol
GET /genetree/member/id/:species/:id
GET /cafe/genetree/id/:id
GET /cafe/genetree/member/symbol/:species/:symbol
GET /cafe/genetree/member/id/:species/:id
GET /alignment/region/:species/:region

使用场景：查找直系同源物、构建系统发育树、提取物种比对。

9 · ensembl_variation

变异查找、VEP 后果、连锁不平衡（LD）、表型映射。

GET  /variation/:species/:id
GET  /variation/:species/pmcid/:pmcid
GET  /variation/:species/pmid/:pmid
POST /variation/:species
GET  /vep/:species/hgvs/:hgvs_notation
POST /vep/:species/hgvs
GET  /vep/:species/id/:id
POST /vep/:species/id
GET  /vep/:species/region/:region/:allele
POST /vep/:species/region
GET  /ld/:species/:id/:population_name
GET  /phenotype/variant/:species/:id
GET  /phenotype/region/:species/:region
GET  /transcript_haplotypes/:species/:id

使用场景：VEP 预测、LD 块、表型关联。

10 · ensembl_ontotax

本体术语搜索和 NCBI 分类学遍历。

GET /ontology/id/:id
GET /ontology/name/:name
GET /taxonomy/id/:id
GET /taxonomy/name/:name

使用场景：GO 术语查找、表型本体、分类学分类。

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 ensembl-mcp-server，请使用以下命令：

npx -y @smithery/cli install @effieklimi/ensembl-mcp-server --client claude

🔧 技术细节

本项目使用 TypeScript MCP SDK 构建，全程使用 TypeScript，具备强大的错误处理能力和简洁的 API 客户端层。通过将工具按生物任务分组，而非按底层 REST 路径分组，提高了对生物学家的友好性。

💻 使用示例

基础用法

以下是一个使用 ensembl_feature_overlap 工具查找特定区域重叠基因的示例：

GET /overlap/region/human/chr17:43-44Mb

高级用法

如果你需要同时使用多个工具进行复杂的查询，可以结合不同工具的端点进行调用。例如，先使用 ensembl_lookup 工具获取基因 ID，再使用 ensembl_sequence 工具检索该基因的序列：

# 获取基因 ID
GET /lookup/symbol/human/BRCA1

# 使用获取的 ID 检索序列
GET /sequence/id/<gene_id>

🤝 贡献代码

我们非常欢迎你的帮助！以下是开始贡献的步骤：

快速联系

• 给开发者发邮件：effie@effie.bio

开发工作流程

1. 分叉仓库
2. 克隆你的分叉仓库：

git clone https://github.com/YOUR_USERNAME/ensembl-mcp-server.git
cd ensembl-mcp-server

3. 安装依赖项：

npm install

4. 运行测试以确保一切正常：

npm test

5. 启动开发服务器：

npm run dev

6. 进行修改并彻底测试
7. 提交拉取请求

可用脚本

• npm run dev - 热重载开发
• npm run start - 运行服务器
• npm test - 运行所有测试
• npm run build - 编译 TypeScript（可选）
• npm run start:prod - 运行编译后的版本