uniprot-mcp-server

---

概要

UniProtKB を使ったタンパク質研究に対応します。機能や遺伝子で検索し、キュレーション済みレコードを取得し、Ensembl、ChEMBL、RefSeq、PDB などの識別子をマッピングして、参照プロテオーム、分類情報、配列を取得します。

ツール

ツール	説明
uniprot_search_proteins	プレーンテキストまたは Lucene フィールドクエリで UniProtKB を検索します。レビュー済み（Swiss-Prot）フィルターを優先的に表示し、サーバー側のファセット件数も任意で取得できます。カーソルページネーションに対応しています。検索の入り口となるツールです。
uniprot_get_entry	アクセッションを指定し、キュレーション済みの完全なエントリーを一括取得します（最大 20 件）。機能、触媒活性、疾患、変異、アイソフォーム、GO 用語、相互参照を含みます。一部の取得に成功した場合も結果を返し、大きすぎるレコードについてはセクションの概要を返します。
uniprot_map_ids	UniProt の非同期 ID マッピングサービスを使ってデータベース間で識別子を変換します。遺伝子名、Ensembl、RefSeq、ChEMBL、PDB、GeneID と UniProtKB アクセッション間の変換に対応しています。予算内でポーリングし、処理中のジョブにはチケットを返し、完了したページには続行用の情報を返します。
uniprot_get_proteome	UPID または NCBI 分類群 ID で参照プロテオームを取得します。タンパク質数、BUSCO 完全性、ゲノムアセンブリをインラインで返し、任意で上限付きのタンパク質ページも取得できます。
uniprot_get_taxonomy	NCBI 分類群 ID または学名で分類レコードを解決します。名前、ランク、親、完全な系統、および任意で直下の子を返します。カーソルページネーションに対応しています。
uniprot_get_sequence	アクセッションに対応する標準アミノ酸配列（FASTA）を、長さと解析済みヘッダーとともに取得します。任意でアイソフォーム配列も取得できます。配列だけを手軽に取得できる方法です。

リソース

リソース	説明
uniprot://entry/{accession}	アクセッションで指定した、厳選された UniProtKB エントリーです。単一のアクセッションに対する uniprot_get_entry のリソースミラーです。
uniprot://taxonomy/{taxonId}	NCBI taxon ID で指定した分類レコードです。名前、ランク、親分類、完全な系統を取得できます。ID を指定した uniprot_get_taxonomy のミラーです。

すべてのリソースデータはツール経由でも取得できるため、ツールのみを利用するクライアントでも不足はありません。UniProtKB は非常に大規模なため、列挙できません。そのため、リソースの list() はありません。検索には uniprot_search_proteins を使用します。

プロンプト

プロンプト	説明
uniprot_protein_dossier	タンパク質調査をガイドするワークフローです。識別子を解決し、厳選されたエントリーを取得して、疾患とバリアントの情報を収集し、構造、文献、バイオアクティビティに関する相互参照を提示します。

機能リファレンス

uniprot_search_proteins _tool

• 平易な言葉で検索する text_search、または Lucene のフィールド構文（gene、organism_id、keyword、go、reviewed、protein_name、family、length、existence、accession）で検索する query のいずれか一方のみを指定します。organism_id はクエリ全体に適用され、対応しない括弧は拒否されます。任意の facets を指定すると、件数の内訳（例：reviewed、model_organism）が返されます
• reviewed の既定値は true（Swiss-Prot のみ）です。false にすると、両方の階層が検索されます（TrEMBL のみを検索するには、query に reviewed:false を指定します）。各検索結果には reviewed、annotationScore、proteinExistence が含まれます
• 前方向のみのカーソルページネーションに対応し、totalResults と実際に適用されたクエリを返します。カーソルは、このツールと、organism／reviewed フィルターを含む組み立て済みのクエリに厳密に結び付けられます。size、fields、facets を変更しても続きの取得には影響しません。クエリの変更、不正なトークン、旧形式の生カーソルは invalid_cursor エラーになります。その場合はカーソルを指定せずに再開してください
• 非アクティブなアクセッション（統合、分割、または削除済み）は、results[] ではなく、理由と置換先を含めて inactive[] に格納されます

---

uniprot_get_entry _tool

• 1 回の呼び出しで最大 20 個のアクセッションを指定できます。アクセッションは uniprot_search_proteins または uniprot_map_ids から取得し、-N のアイソフォーム接尾辞があれば削除してください。レコードはセクションに分かれており、機能、触媒活性、補因子、細胞内局在、疾患、PTM、自然変異、アイソフォーム、ドメイン、GO 用語、キーワード、相互参照が含まれます。fields で出力を絞り込めますが、識別情報と由来を示すフィールドは常に保持されます
• 解決済みのエントリーは succeeded[]、不明または非アクティブなエントリーは failed[] に返されるため、アクセッションが 1 つ不正でもバッチ全体は中断されません。非アクティブなアクセッションのエラーには、統合先、分割後のエントリー、または UniParc ID が示されます
• content[] と structuredContent の合計が UTF-8 で 24,000 バイトを超える場合、初回応答は kind: "outline" を返します。解決済みのアクセッションが 1 つの場合はセクション一覧が返され、大きなバッチの場合はリクエスト順に outlinedEntries が返され、すべての failed[] エントリーが保持されます。概要が返された各アクセッションを個別に再度呼び出し、その後、必要な部分を sections: [...] で指定してください。セクションを明示すると、すべての相互参照 ID を含め、返される項目がすべて表示されます。非常に大きなリストセクションは section_limit（1～500）と section_offset でページ分割され、totalCount と nextOffset が返されます

---

uniprot_map_ids _ツール

• from_db / to_db は検証済みの列挙値です（例：Gene_Name、Ensembl、RefSeq_Protein、ChEMBL、PDB、GeneID、および変換元としての UniProtKB_AC-ID）。不明なデータベースを指定すると、リクエストを行う前に失敗します。レビュー済みアクセッションのみを対象にする場合は UniProtKB-Swiss-Prot を、TrEMBL も含める場合は UniProtKB を指定します。遺伝子シンボルを from_db に指定する場合は、種を選択するために tax_id を組み合わせてください
• ジョブを送信し、時間制限内でポーリングします。ジョブがまだ実行中の場合は、チケット付きで status: "running" を返します。そのチケットだけを渡してポーリングしてください。完了した呼び出しは、1 ページと continuation を含む status: "finished" を返します。continuation だけを渡すと次のページを取得できます。continuation がなければ最後のページです
• unmappedIds には、UniProt が失敗したと報告した識別子のみが列挙されます。UniProtKB の変換先が非アクティブ（統合、分割、または削除）になっている行には、理由と置換先を含む inactive マーカーが付与されます
• 完了済みページの継続リクエストが拒否された場合（HTTP 400）、ページが不明な場合、またはジョブの有効期限が切れている場合は、再開方法を案内する invalid_continuation エラーが返されます。上流の停止は、元の上流エラー分類のまま返されます

---

uniprot_get_proteome _ツール

• upid（例：UP000005640）または taxon_id のいずれか一方だけを指定してください。両方、またはいずれも指定しない場合は検証に失敗します。生物名は、まず uniprot_get_taxonomy で分類群 ID に解決してください
• プロテオームの種類、タンパク質の総数、BUSCO 完全性（スコア、完全・断片化・欠損の数、系統データセット）、ゲノムアセンブリのアクセッションを返します
• タンパク質は include_proteins でオプトインできます（ヒトでは約 147,506 件）。結果は、次ページ用のカーソル付きで上限のあるページとして返されます。query（UniProtKB Lucene 構文）で絞り込めます。カーソルは、解決済み UPID、クエリの完全一致、およびツールに紐付けられます。同じプロテオームに解決される分類群 ID と UPID の間でカーソルを共有でき、size は変更できます。対象の変更、または従来形式の生カーソルを指定すると invalid_cursor エラーが返されます。その場合はカーソルを指定せずに再開してください

---

uniprot_get_taxonomy _ツール

• taxon_id（NCBI の数値 ID）または name（学名）のいずれか一方だけを指定してください。両方、またはいずれも指定しない場合は検証に失敗します。uniprot_search_proteins（organism_id）と uniprot_get_proteome（taxon_id）で必要となる分類群 ID を取得できます
• 学名と一般名、ニーモニック、ランク、親分類群、および完全な系統（根から近い祖先まで）を返します
• include_children を指定すると、直接の子分類群が追加されます。1 ページあたり 100 件で、合計件数と次のページ用の cursor が含まれます。異なる分類群でカーソルを使うと invalid_cursor エラーが返されます

---

uniprot_get_sequence _ツール

• 正規配列とその長さ、および解析済みの FASTA ヘッダーを返します。include_isoforms を指定すると、アイソフォーム配列も追加されます。アクセッションは uniprot_search_proteins または uniprot_map_ids から取得してください（-N 形式のアイソフォーム接尾辞があれば取り除いてください）
• 統合されたアクセッションでは、統合先の配列が返され、mergedFrom にリクエストしたアクセッションが含まれます。分割または削除されたアクセッションでは、置換先または UniParc ID を示す not_found エラーが返されます

---

uniprot://entry/{accession} _リソース

• URI で指定する単一アクセッションのレコードで、uniprot_get_entry と同じ内容です。非アクティブなアクセッション（統合、分割、または削除）を指定すると not_found エラーが返されます
• 非常に大きなエントリーの場合は、識別情報の要約（アクセッション、エントリー名、タンパク質名、遺伝子、生物、長さ、レビュー済みかどうか、注釈スコア、タンパク質の存在状況）とセクションの概要を返します。URI ではセクションを指定できないため、特定のセクションを取得するには uniprot_get_entry（sections: [...]）を使用してください

---

uniprot://taxonomy/{taxonId} _リソース

• NCBI 分類群 ID で指定します。例：ヒトの場合は uniprot://taxonomy/9606
• 学名と一般名、ニーモニック、ランク、親分類群、および完全な系統を返します。include_children を指定しない場合の uniprot_get_taxonomy と同じ形式です
• ツールのみを利用するクライアントは、uniprot_get_taxonomy を通じて同じデータを取得できます

---

uniprot_protein_dossier _{プロンプト}

• 引数：identifier は必須（遺伝子名、アクセッション、またはタンパク質名）、organism は曖昧さを解消する場合に任意で指定
• 生成されたメッセージに組み込まれた5段階のワークフロー：識別子を解決 → エントリーを取得 → 機能／局在／由来を要約 → 疾患とバリアントを取得 → 構造（PDB）、生物活性（ChEMBL）、引用文献（PubMed）の相互参照を提示
• すべての指示を含む単一のユーザーロールメッセージを返します。個別のアシスタント導入メッセージはありません

特長

@cyanheads/mcp-ts-core を基盤としています。stdio および Streamable HTTP トランスポート、プラグイン可能な認証（none／jwt／oauth）、交換可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレースに対応した構造化ログを利用できます。

UniProt 固有の特長：

• API キー不要 — UniProt REST に API キーは必要ありません。rest.uniprot.org 互換のベース URL であれば使用でき、プライベートミラーの場合は UNIPROT_BASE_URL を上書きします
• エントリーの一括取得 — 1回の往復で複数のアクセッションを取得し、見つからないものにはフラグを付けます
• 非同期 ID マッピング — 上限付きポーリング、実行中ジョブを再開できるチケット、ページ分割された結果に対応します

エージェントに適した出力：

• 由来情報は飾りではなくデータです — reviewed、annotationScore、proteinExistence、およびフィールドごとの PubMed／ECO エビデンスがすべてのレコードに含まれるため、エージェントは手動アノテーションと予測アノテーションを評価できます
• 部分的な失敗を適切に処理 — uniprot_get_entry はバッチ全体を中断せず、アクセッションごとの succeeded[]／failed[] 行を返します
• 明示的な出力形式 — uniprot_get_entry は kind: "full" | "outline" を返し、uniprot_map_ids は ticket または continuation のいずれかを返します
• 欠損のない疎なデータ — 上流に存在しないフィールドは存在しないままにし、捏造しません（キュレーション済みのセクションの多くは、TrEMBL エントリーでは正当に欠落しています）

はじめに

公開ホストインスタンス

公開インスタンス（https://uniprot.caseyjhand.com/mcp）を利用できます。インストールは不要です。Streamable HTTP 経由で、任意の MCP クライアントを接続してください。

{
  "mcpServers": {
    "uniprot-mcp-server": {
      "type": "streamable-http",
      "url": "https://uniprot.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加してください。UniProt REST は API キー不要です。

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

または npx を使用します（Bun は不要です）。

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

または Docker を使用します。

{
  "mcpServers": {
    "uniprot-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/uniprot-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 キー不要 — UniProt REST はキー不要で公開されています。データは UniProt のもので、CC BY 4.0 です。

インストール

1. リポジトリをクローンします。

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

2. ディレクトリに移動します。

cd uniprot-mcp-server

3. 依存関係をインストールします。

bun install

設定

すべての設定は、src/config/server-config.ts の Zod スキーマを使って起動時に検証されます。UniProt REST はキーを必要としないため、以下のサーバー固有の変数はすべて任意のオーバーライドです。

変数	説明	デフォルト
UNIPROT_BASE_URL	UniProt REST のベース URL です。プライベートミラーまたはテスト用に上書きします。	https://rest.uniprot.org
UNIPROT_TIMEOUT_MS	リクエストごとの HTTP タイムアウト（ミリ秒）です。	30000
UNIPROT_ID_MAPPING_BUDGET_MS	チケットを返すまでの ID マッピングのポーリングに割り当てる時間です。UNIPROT_TIMEOUT_MS より小さくする必要があります。	8000
UNIPROT_DEFAULT_PAGE_SIZE	呼び出し元が指定しない場合に、検索とプロテオームのタンパク質一覧で使用するデフォルトのページサイズです。	25
MCP_TRANSPORT_TYPE	トランスポートです。stdio または http を指定します。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_AUTH_MODE	認証モードです。none、jwt、または oauth を指定します。	none
MCP_SESSION_MODE	HTTP セッションモードです。auto、stateful、または stateless を指定します。デフォルトではサーバーはステートレスです。	stateless
MCP_LOG_LEVEL	ログレベル（RFC 5424）です。	info
LOGS_DIR	ログファイルのディレクトリです（Node.js のみ）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しごとに、引数と結果をキー名で秘匿化し、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）を上限として記録します。自由形式の値に含まれるシークレットは秘匿化されません。	false
STORAGE_PROVIDER_TYPE	ストレージバックエンドです。	in-memory
OTEL_ENABLED	OpenTelemetry instrumentation（スパン、メトリクス、完了ログ）を有効にします。	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 test:coverage   # Test suite with coverage, enforcing the framework thresholds
  bun run lint:mcp        # Validate MCP definitions against spec
  

Docker

docker build -t uniprot-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/uniprot-mcp-server:latest

Dockerfile のデフォルトは HTTP トランスポート、ステートレスセッションモードで、ログは /var/log/uniprot-mcp-server に出力されます。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() エントリーポイントです。ツール、リソース、プロンプトを登録し、UniProt サービスを初期化します。
src/config	サーバー固有の環境変数の解析と、Zod による検証を行います。
src/mcp-server/tools	ツール定義（*.tool.ts）です。UniProtKB、ID マッピング、プロテオーム、分類、配列を扱う 6 つのツールがあります。
src/mcp-server/resources	リソース定義（*.resource.ts）です。エントリーと分類の ID 指定ミラーを提供します。
src/mcp-server/prompts	プロンプト定義（*.prompt.ts）です。タンパク質ドシエのワークフロー用プロンプトがあります。
src/services/uniprot	rest.uniprot.org REST クライアントです。検索、一括エントリー、ID マッピング、プロテオーム、分類、FASTA に加え、正規化されたドメイン型を提供します。
tests/	src/ に対応する単体テストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md（および内容が完全に同一の AGENTS.md）を参照してください。要点は次のとおりです。

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

コントリビューション

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

bun run devcheck
bun run test

ライセンス

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