ensembl-mcp-server

---

概述

通过 Ensembl REST API 获取脊椎动物和其他模式生物的基因、序列和变异数据。查询基因、获取序列、预测变异后果、查找直系同源基因，并交叉引用外部数据库。

工具

工具	描述
ensembl_list_species	列出 Ensembl 支持的物种及其显示名称、常用名称、组装版本、分类单元 ID 和分区
ensembl_lookup_gene	按符号（包括同义词和旧符号）及物种，或按稳定 ID，查找基因的 Ensembl ID、基因组位置、生物类型和转录本列表
ensembl_get_sequence	获取基因、转录本、蛋白质或基因组区域的 DNA、cDNA、CDS 或蛋白质序列
ensembl_query_region	查找与染色体区域重叠的基因组特征（基因、转录本、变异、调控元件、外显子）
ensembl_predict_variant	使用 Ensembl Variant Effect Predictor (VEP) 预测序列变异的功能后果
ensembl_get_homology	查找跨物种的基因直系同源基因和／或旁系同源基因，并获取序列一致性百分比和分类层级
ensembl_get_xrefs	获取基因的跨数据库引用——HGNC、UniProt、EntrezGene、OMIM、RefSeq、Reactome 等

资源

资源	描述
ensembl://gene/{id}	按稳定 ID（ENSG…）查询基因记录 — 包含位置、生物类型、描述和转录本列表
ensembl://transcript/{id}	按稳定 ID（ENST…）查询转录本记录 — 包含所属基因、位置、生物类型、是否为规范转录本以及长度
ensembl://species	该端点默认分区支持的 Ensembl 物种（默认端点为脊椎动物）
ensembl://species/{division}	某个分区支持的物种（EnsemblVertebrates、EnsemblPlants、EnsemblFungi、EnsemblMetazoa、EnsemblProtists）

物种资源返回内部名称排序靠前的 50 个物种；ensembl_list_species 工具会分页获取其余物种，并按名称筛选。

提示词

提示词	描述
ensembl_gene_dossier	用于整理完整基因档案的结构化工作流：符号 → ID + 位置 → 序列 → 变异 → 直系同源物 → xrefs

功能参考

Ensembl 的稳定 ID 端点会将带版本号的 ID（ENSG00000139618.19）视为未找到，因此所有接受 Ensembl 稳定 ID 的工具和资源都会在请求前去掉 ENS… ID 末尾的 .N，并返回当前版本。ensembl_predict_variant 的 HGVS 输入（ENST00000380152.8:c.2T>A）会保留版本号，其他来源的 ID（AT3G52430.1）则会原样转发。

ensembl_list_species _工具

• 可选参数 division（EnsemblVertebrates、EnsemblPlants、EnsemblFungi、EnsemblMetazoa、EnsemblProtists；省略时使用端点默认值 — 脊椎动物，在 GRCh38 上约有 356 个物种）和 nameContains，用于匹配名称、显示名称和常用名称中的子字符串
• 返回其他工具所需的内部名称（homo_sapiens），以及显示名称、常用名称、分类单元 ID、组装版本和分区
• 按内部名称排序，并通过 offset（默认值 0）和 max_results（默认值 50，0 表示不设上限）分页；totalCount 报告所有匹配项，若还有后续结果，nextOffset 指明下一页的起始位置

---

ensembl_lookup_gene _工具

• 必须且只能指定 symbol（以及 species，默认值为 homo_sapiens）、id、ids 或 symbols 中的一项（最多提交 1,000 项；处理前 20 个去重并去除首尾空格后的查询）；expand_transcripts（默认值 false）可添加包含生物类型和规范标记的转录本列表
• 不展开时，canonicalTranscript 会标识规范转录本；查询转录本 ID 时也会返回 parentGeneId。展开后的转录本在可用时会包含 maneSelect RefSeq 登录号（BRCA2：ENST00000380152.8、NM_000059.4）
• 若某个符号不是当前基因名称，则会回退查询同义词和曾用符号（HER2 → ERBB2），并通过 matchedAlias 报告；若多个基因共用同一名称（MDR1），则返回 ambiguous 及候选项，可改用 id 重试
• 单项查询返回 gene（或 ambiguous）；batch 返回按顺序排列的 succeeded 项（包含提交的 query）、failed 项（包含 query、reason（not_found、带有 candidates 的 ambiguous，或 unavailable）、error 和 recovery），以及超出处理上限的 omitted 查询。不会请求或报告被省略的查询为失败；请单独重新提交。错误：not_found、invalid_species、no_input、conflicting_input

---

ensembl_get_sequence _工具

• 稳定 ID（ENSG…/ENST…/ENSP…）或区域（species:chr:start-end，或与 species 搭配的 chr:start-end；最多 10,000,000 个碱基）；type 为 genomic（默认值）、cdna、cds 或 protein——cdna 和 cds 仅接受转录本 ID，protein 接受转录本或蛋白质 ID；expand_5prime/expand_3prime 用于添加侧翼碱基
• 区域可附加 :1/:-1 链后缀（1:1000000-1000020:-1 会返回反向互补序列）；脊椎动物的线粒体名称为 MT（果蝇中为 mitochondrion_genome，秀丽隐杆线虫中为 MtDNA）；若 M/chrM 无法解析为线粒体，则会因 invalid_region 被拒绝
• 返回由 offset（默认值 0）和 max_length（默认值 10000，0 表示不设上限）指定的窗口；length 为完整序列长度，truncated/nextOffset 指明续读位置
• 错误：not_found、type_mismatch（也适用于对蛋白质 ID 请求 genomic/cdna/cds，或对非编码转录本请求 protein/cds）、invalid_species、missing_species、invalid_region（也适用于包含冒号但不是有效区域的 ID）

---

ensembl_query_region _工具

• region 为 species:chr:start-end，或与 species 搭配的 chr:start-end（最多 5,000,000 个碱基；不接受倒置的坐标；线粒体命名规则同 ensembl_get_sequence）；feature 默认为 ["gene"]，也接受 transcript、variation、regulatory、exon；可选的 biotype 筛选器区分大小写（protein_coding、lncRNA）。筛选后结果为空时，建议移除筛选条件，不要据此推断该位点位于基因间区
• max_results 限制列表长度（默认值 100，0 表示不设上限），totalCount 返回实际总数；assemblyName 指明坐标所属的组装版本，外显子行包含 parentId 和 rank。错误：invalid_region、invalid_species、missing_species

---

ensembl_predict_variant _工具

• variant 可为 HGVS（相对于转录本或基因组）、区域+等位基因（chr:start:end:strand/allele），或 dbSNP rsID
• 返回最严重的后果、逐转录本影响（HIGH/MODERATE/LOW/MODIFIER），以及具有临床意义的共定位已知变异。错误：invalid_notation、not_found、invalid_species
• 所有输入方式都会请求 HGVS、canonical 和 MANE 注释。后果保留 variantAllele、可选的 canonical/maneSelect、HGVS 以及可用的 SIFT/PolyPhen 预测分数对；记录保留 alleleString
• 共定位的 clinicalSignificance 是汇总结果，并非对所提交等位基因的分类。clinicalSignificanceByAllele 保留明确的逐等位基因术语，clinicalSignificanceReferenceAllele 标明其参考等位基因；缺失的注释不会返回
• max_transcript_consequences 和 max_pubmed_ids_per_variant（各自默认值为 10，0 表示不设上限；include_all_colocated_pubmed 可取消 PubMed 数量上限）限制结果，而 transcriptConsequencesTotal 和 pubmedTotal 返回完整计数

---

ensembl_get_homology _工具

• symbol（以及 species，默认值为 homo_sapiens）和 id 中必须且只能指定一个；type 为 orthologues（默认值）、paralogues 或 all；可选的 target_species 筛选器
• max_results 限制列表长度（默认值 25，0 表示不设上限），totalCount 返回实际总数。错误：not_found、invalid_species（未知的 species 或 target_species）、no_input、conflicting_input
• 每一行都会保留可选的 targetProteinId，可供 ensembl_get_sequence 使用，且 type:"protein"。可选的 targetSymbol 来自对返回行中不同基因 ID 的查询，按每批最多 1,000 个 ID 分批进行，共享五秒预算，并受调用剩余截止时间限制，且不重试。若名称缺失或查询失败，则保留所有主要同源基因，并附带提示；取消操作仍会中止请求

---

ensembl_get_xrefs _工具

• 必填 id（ENSG…/ENST…/ENSP…）；可选 dbname 筛选器（例如 HGNC、Uniprot_gn、EntrezGene、MIM_GENE、RefSeq_mRNA、用于基因通路的 Reactome_gene、用于翻译通路的 Reactome、GO）
• 默认情况下，all_levels:false 会查询指定对象所在层级。设置 all_levels:true 可包含基因的转录本和翻译产物引用，无论 dbname 为何；例如，基因层级的 RefSeq_mRNA 可能需要此设置或转录本 ID。空列表仍会成功返回 totalCount:0。错误：not_found

---

ensembl://gene/{id} _资源

• id 是基因稳定 ID（ENSG…）；版本后缀可选，且会被移除
• 返回位置信息、生物类型、描述和转录本列表。错误：not_found

---

ensembl://transcript/{id} _资源

• id 是转录本稳定 ID（ENST…）；版本后缀可选，且会被移除
• 返回父基因、位置信息、生物类型、规范标记和长度。错误：not_found

---

ensembl://species _资源

• 无参数 — 覆盖端点的默认分部（脊椎动物；默认 GRCh38 端点约有 356 个物种）
• 按内部名称返回前 50 个物种，并提供 totalCount、shown 和 truncated；如果响应正文被截断，其中的 notice 会指向 ensembl_list_species（offset、max_results），以获取其余结果
• 对于指定分部，请改为读取 ensembl://species/{division}

---

ensembl://species/{division} _资源

• 必填 division：EnsemblVertebrates、EnsemblPlants、EnsemblFungi、EnsemblMetazoa 或 EnsemblProtists
• 按内部名称返回该分部的前 50 个物种 — 包含内部名称、显示名称、组装版本、分类群 ID 和分部 — 并提供 totalCount、shown 和 truncated；如果响应正文被截断，其中的 notice 会指向 ensembl_list_species（division、offset、max_results），以获取其余结果

---

ensembl_gene_dossier _提示词

• 参数：必填 gene_symbol；可选 species（默认值为 homo_sapiens）
• 按顺序执行 7 步工作流：解析基因 → 获取蛋白质序列 → 查找基因座中的变异 → 预测变异后果 → 查找跨物种直系同源基因 → 获取外部数据库 ID → 汇总档案

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

Ensembl 专属功能：

• 无需密钥的 REST API — 无需 API 密钥；Ensembl REST 完全公开，每小时可处理 55,000 个请求
• 针对 429 响应（遵循 Retry-After）和临时 5xx 错误进行重试
• 上游调用单次尝试超时为 180 秒，每次调用超时为 240 秒，因此 Ensembl 卡住时会失败，而不会一直挂起
• 批量查询使用 POST /lookup/id 和 POST /lookup/symbol/{species}，以避免 N+1 次往返
• 通过 ENSEMBL_BASE_URL 支持 GRCh37 旧版；将整个服务指向 https://grch37.rest.ensembl.org，即可为较旧的组装版本处理临床工作流
• 所有包含坐标的响应都会附带组装版本名称，确保 Agent 看到的基因组位置始终有组装版本作为上下文

便于 Agent 使用的输出：

• ensembl_get_sequence 默认返回有界窗口（10,000 个字符），并附带完整长度和用于继续读取的 nextOffset
• ensembl_list_species 用于发现物种内部名称；每页返回 50 个，并附带 nextOffset
• ensembl_get_xrefs 返回的交叉引用 ID 被说明为蛋白质和文献服务的输入；ensembl_gene_dossier 提示词串联了 7 个工具中的 6 个

开始使用

公共托管实例

可使用公共实例 https://ensembl.caseyjhand.com/mcp，无需安装。该实例提供 Streamable HTTP；不同客户端的配置格式各不相同。

对于 Claude Code：

claude mcp add --transport http ensembl-mcp-server https://ensembl.caseyjhand.com/mcp

对于 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "ensembl-mcp-server": {
      "type": "streamableHttp",
      "url": "https://ensembl.caseyjhand.com/mcp"
    }
  }
}

对于 Cursor（mcp.json）：

{
  "mcpServers": {
    "ensembl-mcp-server": {
      "url": "https://ensembl.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在 Settings → Connectors 下添加远程服务。

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "ensembl-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/ensembl-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "ensembl-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/ensembl-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "ensembl-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/ensembl-mcp-server:latest"
      ]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥 — Ensembl REST 完全公开。

安装

1. 克隆仓库：

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

2. 进入目录：

cd ensembl-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env if you need to override ENSEMBL_BASE_URL (e.g. for GRCh37)

配置

所有配置均通过 src/config/server-config.ts 中的 Zod schema 在启动时进行验证。

变量	说明	默认值
ENSEMBL_BASE_URL	Ensembl REST API 基础 URL。可将其覆盖为 GRCh37（https://grch37.rest.ensembl.org）或本地镜像。	https://rest.ensembl.org
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_HTTP_ENDPOINT_PATH	HTTP 端点路径	/mcp
MCP_SESSION_MODE	HTTP 会话模式：auto、stateful 或 stateless	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）	info
LOGS_DIR	日志文件目录（仅限 Node.js）	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果，按键名进行脱敏，并限制在 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认值为 16384）以内。自由格式值中的密钥不会被脱敏。	false
OTEL_ENABLED	启用 OpenTelemetry	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t ensembl-mcp-server .
docker run --rm -p 3010:3010 ensembl-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/ensembl-mcp-server。默认会安装 OpenTelemetry 对等依赖项；如需省略这些依赖项，请使用 --build-arg OTEL_ENABLED=false 构建。

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 注册工具、资源和提示词，并初始化服务
src/config	使用 Zod 解析和验证服务专属环境变量
src/mcp-server/tools	工具定义（*.tool.ts）— 7 个工具
src/mcp-server/resources	资源定义（*.resource.ts）— 基因、转录本、物种
src/mcp-server/prompts	提示词定义（*.prompt.ts）— 基因档案工作流
src/services/ensembl	Ensembl REST API 客户端 — HTTP、速率限制处理、重试、错误规范化
tests/	与 src/ 结构对应的单元测试和集成测试

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要内容如下：

• 处理程序抛出异常，框架负责捕获 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求范围的日志记录，使用 ctx.state 进行租户范围的存储
• 在 src/index.ts 的 createApp() 数组中注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出 schema；绝不要编造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。