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 - 運行編譯後的版本