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}	1 つの区分でサポートされる種（EnsemblVertebrates、EnsemblPlants、EnsemblFungi、EnsemblMetazoa、EnsemblProtists）

種リソースは、内部名で最初の 50 種を返します。ensembl_list_species ツールは残りをページ分けして取得し、名前で絞り込みます。

プロンプト

プロンプト	説明
ensembl_gene_dossier	完全な遺伝子プロファイルを組み立てるための構造化されたワークフロー：シンボル → ID + 位置 → 配列 → 変異 → オルソログ → xref

機能リファレンス

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 つのみを指定します（最大 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 では、送信された query を含む順序どおりの succeeded 項目、query、reason（not_found、candidates を伴う ambiguous、または unavailable）、error、recovery を含む failed 項目、および処理上限を超えた 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 またはタンパク質 ID から取得できます。expand_5prime／expand_3prime は両側の塩基を追加します
• 領域には :1／:-1 の鎖サフィックスを指定します（1:1000000-1000020:-1 は逆相補鎖を返します）。脊椎動物ではミトコンドリアは MT、Drosophila では mitochondrion_genome、C. elegans では 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
• 各行には、type:"protein" を指定した ensembl_get_sequence で使用できる任意の targetProteinId が保持されます。任意の targetSymbol は、返された行の重複しない遺伝子 ID を最大1,000件ずつに分けて検索して取得します。検索には、呼び出しの残り時間を上限とする5秒の予算が1回だけ適用され、再試行は行われません。名前がない場合や検索に失敗した場合は、通知とともにすべての主要な相同遺伝子が保持されます。ただし、キャンセルされた場合は処理が中断されます

---

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固有の機能：

• APIキー不要のREST API — Ensembl RESTは完全に公開されており、55,000リクエスト／時に対応します。
• 429レスポンス（Retry-Afterを尊重）および一時的な5xxエラーを再試行します。
• 上流への呼び出しは、1回の試行につき180秒、1回の呼び出しにつき240秒でタイムアウトします。そのため、Ensemblの応答が停止した場合も、処理がハングせずに失敗します。
• バッチ検索ではPOST /lookup/idとPOST /lookup/symbol/{species}を使用し、N+1回のラウンドトリップを回避します。
• ENSEMBL_BASE_URLによるGRCh37のレガシーサポート — 古いアセンブリを使用する臨床ワークフローでは、サーバー全体をhttps://grch37.rest.ensembl.orgに向けます。
• 座標を含むすべてのレスポンスにアセンブリ名が含まれるため、エージェントがアセンブリ情報のないゲノム位置を参照することはありません。

エージェント向けの出力：

• ensembl_get_sequenceは、長さの上限が設定されたウィンドウ（デフォルトで10,000文字）を、全長と続きの取得に使うnextOffsetとともに返します。
• ensembl_list_speciesは内部種名を調べるためのステップです。1ページあたり50種を返し、続きの取得に使うnextOffsetを含みます。
• ensembl_get_xrefsのXref 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 スキーマを使用して起動時に検証されます。

変数	説明	デフォルト
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）— gene、transcript、species
src/mcp-server/prompts	プロンプト定義（*.prompt.ts）— gene dossier ワークフロー
src/services/ensembl	Ensembl REST API クライアント — HTTP、レート制限処理、再試行、エラーの正規化
tests/	src/ に対応するユニットテストと統合テスト

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は以下のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックに try/catch を使用しないでください
• リクエストスコープのログには ctx.log、テナントスコープのストレージには ctx.state を使用します
• 新しいツールとリソースは、src/index.ts の createApp() 配列に登録します
• 外部 API の呼び出しはラップします。生データを検証し、ドメイン型に正規化してから、出力スキーマに沿って返します。不足しているフィールドを捏造しないでください

貢献

問題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。