protein-mcp-server

---

概要

実験的なタンパク質構造（PDB）と予測されたタンパク質構造（AlphaFold）を、ひとつのインターフェースで利用できます。RCSB、AlphaFold DB、3D-Beacons、UniProt、InterPro、Foldseek にわたって、構造とそのリガンドを検索、取得、アラインメント、アノテーションできます。API キーは不要です。

ツール

ツール	説明
protein_search_structures	テキスト、配列、または生物種／手法／分解能で実験構造と予測構造を検索します。ファセットも任意で指定できます
protein_get_structure	実験構造、予測構造、または利用可能な最適な構造のメタデータと座標 URL を取得します
protein_find_similar	配列ホモログ（RCSB mmseqs2）またはフォールドホモログ（Foldseek）を検索します
protein_track_ligands	リガンドをコンポーネント ID に対応付け、そのリガンドを含む構造を検索するか、結合部位を特定します
protein_compare_structures	TM-align または jFATCAT で、参照構造またはすべてのペアに対して構造をアラインメントします
protein_analyze_collection	PDB コレクションの件数、ヒストグラム、タイムライン、クロス集計を作成します
protein_get_annotations	UniProt の特徴とバリアントに加え、GO 用語を含む InterPro ドメインを取得します

リソース

リソース	説明
pdb://{entry_id}	PDB エントリの実験構造の概要
af://{uniprot}	UniProt アクセッションに対応する AlphaFold DB の予測構造の概要

リソースを表示しないクライアントでも利用できるよう、どちらのリソースにも protein_get_structure からアクセスできます。

機能リファレンス

protein_search_structures _ツール

• query、sequence（mmseqs2 検索。min_identity／max_evalue はこれを指定した場合にのみ適用）、organism、method、max_resolution のうち少なくとも 1 つを指定します。content_type は experimental、predicted、all（デフォルト）のいずれかです。limit／start で、1 ページあたり最大 100 件（デフォルト 25 件）のヒットを取得できます
• sequence は 10 残基以上である必要があります。空白は除去され、大文字・小文字は正規化されます。無効な配列は invalid_sequence として失敗します。各ヒットには source と、ほかのツールに渡せるエントリ id が含まれます
• オプションの facets（method、organism、polymer_type、resolution、release_year、molecular_weight）を指定すると、ディメンションごとに最大 PROTEIN_FACET_BUCKET_CAP 件のバケットに制限された内訳が追加されます

---

protein_get_structure _ツール

• source: experimental（デフォルト）では、PDB エントリ ID と、検索で返された AF_*／MA_* 計算モデル ID（これらは source: predicted として返されます）を指定します。predicted では、pLDDT／PAE を含む AlphaFold モデルの UniProt アクセッションを指定します。best_available では UniProt アクセッションを指定し、最も高解像度の実験構造、またはそれがない場合は最良の予測を返します。1 回の呼び出しにつき最大 PROTEIN_MAX_BATCH_IDS 件の ID（デフォルト 25 件）を指定できます
• 解決できない ID は failed[] に格納され、上限を超えた ID は requested／processed に示されます。解決できる ID がない場合、呼び出しは all_failed として失敗し、ID が source に適合しない場合は mixed_id_types として失敗します。レコードには、存在するファイルの coordinateUrls が含まれます
• include_coords を指定すると、サイズ上限の範囲内で座標テキストをインラインで含めます。上限を超えたバッチは overflow の概要を返すため、sections: [ids] を指定して再呼び出しできます

---

protein_find_similar _ツール

• by: sequence は、sequence、pdb_id、uniprot を使って同期的な RCSB mmseqs2 検索を実行し、max_evalue／min_identity でフィルタリングします。by: structure は、databases で別途指定しない限り、pdb100 + afdb50 を対象に、pdb_id または uniprot から非同期の Foldseek 検索を実行します。もう一方のモードだけが読み取るフィールドを指定すると、mode_mismatched_field として失敗します。1 ページあたり最大 100 件（デフォルト 25 件）のヒットを取得できます
• 配列には protein_search_structures と同じルールが適用され、直接指定した sequence は識別子より優先されます。ヒットには source（構造ヒットの場合は database も）が含まれ、score 順に並びます。レスポンスには totalCount と nextStart が含まれます
• ポーリング上限に達しても構造検索ジョブが実行中の場合は、ticketId を含む status: computing が返されます。ticket_id を指定して再呼び出しすると処理を再開できます。複数鎖構造は、query（0 始まり、デフォルト 0）で queryCount のうち 1 つの鎖を指定して検索します

---

protein_track_ligands _ツール

• mode は find_ligand（query：名前または化学式）、structures_with_ligand（comp_id）、binding_site（pdb_id、comp_id は省略可能）のいずれかです。モードに必要な入力がない場合は missing_param として失敗します。limit は 1～100（デフォルト 25）で、start を使って後者 2 つのモードのページを指定できます
• find_ligand は、化学式、重量、SMILES、InChIKey を含むコンポーネント ID を返し、depositionCount 順に並べます。候補プールが途中で打ち切られた場合は、totalCount と candidatesConsidered でその状況を確認できます。structures_with_ligand は、解像度の高い順にエントリを一覧表示します
• binding_site は、接触距離を含むポケット残基を返します。残基番号は、ラベル（asymId、seqId）と著者（authAsymId、authSeqId）の両方の名前空間で示されます。実験構造のみが対象です

---

protein_compare_structures _tool

• PROTEIN_MAX_COMPARE_STRUCTURES（デフォルトは10、最大25）までの2つの構造を指定します。それぞれに pdb_id と、任意でラベル名前空間の chain を指定します。method は tm-align（デフォルト）、fatcat-rigid、fatcat-flexible のいずれかです。reference は first（デフォルト）または all_pairs です。timeout_s（5～120）で、ペアごとのポーリング予算を設定します。
• 各ペアの行には、status（complete、computing、failed）、tmScore、rmsd、alignedResidues、modeledResidues、coverage が含まれます。TM-score は a の長さで正規化されるため、ペアの順序を逆にすると値が変わります。上流サービスから提供される場合は、similarityScore と sequenceSimilarity も含まれます。
• 計算中のペアはジョブの uuid を返します。再送信する代わりに、{ a, b, uuid } を resume[] に指定して再度呼び出すと、ジョブをポーリングできます。method またはペアが一致しない場合は、それぞれ resume_method_mismatch または resume_job_mismatch として失敗します。

---

protein_analyze_collection _tool

• group_by には、method、organism、polymer_type、resolution、release_year、molecular_weight のいずれか1つ、またはクロス集計用に異なる2つを指定します。query、organism、method、max_resolution、content_type（デフォルトは experimental）で対象範囲を指定します。interval は、resolution／molecular_weight の数値ビン幅、または release_year の "year" を指定します。
• total と bucketsReturned を返します。バケットには label と count が含まれます（数値ビンには rangeFrom／rangeTo も含まれます）。各ディメンションには missingValueCount も含まれます。
• bucket_limit（1～500、デフォルトは PROTEIN_FACET_BUCKET_CAP）は、各ディメンションの上限を個別に設定します。結果が切り詰められた場所は truncated と notice に示されます。

---

protein_get_annotations _tool

• uniprot アクセッション、または UniProt 相互参照を通じて解決される pdb_id を指定します（作成者の chain を指定すると、対応するアクセッションを選択します）。include は features、domains、variants、all のいずれか（デフォルト）です。limit は各クラスを個別にページ分割します（1～200、デフォルトは50）。独立したゼロベースの features_offset、variants_offset、domains_offset も指定できます（デフォルトは0）。
• UniProt のフィーチャーと天然バリアント、および GO タームを含む InterPro ドメインを返します。PDB エントリーが複数のアクセッションに対応する場合は、作成者の最小チェーンを使用し、残りを ambiguity に列挙します。
• 要求した各クラスには、featuresTotal、variantsTotal、domainsTotal のいずれかが含まれます。次のレコードがあるページでは、truncated が設定され、次のオフセットが notice に示されます。
• 失敗は missing_identifier、invalid_accession、no_uniprot_mapping、chain_not_found として分類されます。

---

pdb://{entry_id} _resource

• entry_id は PDB エントリー ID です（例：4HHB）。タイトル、手法、分解能、生物種、リガンド、authAsymIds と labelAsymIds の両方を含む polymerEntities を、application/json で返します。
• source: experimental を指定した protein_get_structure と同じデータです。

---

af://{uniprot} _resource

• uniprot は UniProt アクセッション、または AlphaFold DB エントリー ID です（例：AF-P69905-F1）。meanPlddt、confidenceBuckets、cifUrl／pdbUrl／bcifUrl、modelVersion を、application/json で返します。
• source: predicted を指定した protein_get_structure と同じデータです。

機能

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

PDB / AlphaFold 固有の機能：

• 検索、取得、比較では、実験構造（PDB）と予測構造（AlphaFold DB、ModelArchive、3D-Beacons プロバイダー）を同じ方法で扱います
• RCSB、AlphaFold DB、3D-Beacons、UniProt、InterPro、Foldseek はすべてキーなしで利用できます
• コレクション分析は RCSB のファセットエンジンで実行され、一致するエントリではなくバケット数を返します
• Foldseek とアラインメントのジョブは PROTEIN_ASYNC_POLL_TIMEOUT_MS（デフォルト 30 s）までポーリングし、その後、ブロックせずに再開ハンドル（ticketId、ペアごとの uuid）を返します
• チェーンの名前空間は分離されています。authAsymIds は protein_get_annotations の chain に、labelAsymIds は protein_compare_structures の chain に渡します

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

• 出典情報：すべての検索結果に source（experimental / predicted）と、その背後にあるエンジンまたはデータベースが示されます。また、protein_get_structure と protein_get_annotations には attribution ブロックが含まれます（上流データのライセンスを参照）
• 部分的な失敗を適切に処理：failed[] の行とペアごとの status により、1 つの不正な ID またはペアでリクエスト全体が失敗することはありません
• ページングと注意事項：ページ分割対応のツールは totalCount と nextStart を返します。末尾を超える start は一致なしとは別に notice で示され、すべての注意事項はこの notice にまとめられます

はじめに

公開ホストインスタンス

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

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

セルフホスト／ローカル

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

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

または npx を使用する場合（Bun は不要です）：

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

または Docker を使用する場合：

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/protein-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 キーは不要です。すべての上流サービスは公開されています。

インストール

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

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

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

cd protein-mcp-server

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

bun install

4. 環境を設定します（任意）：

cp .env.example .env
# every variable has a working default

設定

すべての変数は任意です。

変数	説明	デフォルト
PROTEIN_ASYNC_POLL_TIMEOUT_MS	非同期アラインメントまたは Foldseek ジョブが computing を返すまでのポーリング時間（最小 1000）。	30000
PROTEIN_MAX_BATCH_IDS	protein_get_structure 呼び出しあたりの最大 ID 数（1～100）。	25
PROTEIN_MAX_COMPARE_STRUCTURES	protein_compare_structures 呼び出しあたりの最大構造数（2～25）。	10
PROTEIN_FACET_BUCKET_CAP	protein_search_structures のファセットおよび protein_analyze_collection のデフォルトにおける、ディメンションごとのバケット数（1～500）。	50
PROTEIN_FANOUT_CONCURRENCY	ID ごとおよびペアごとのファンアウトにおける、上流リクエストの最大同時実行数（1～16）。	5
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。サーバーがコード内で宣言する stateless モードを上書きします。	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）。	info
OTEL_ENABLED	OpenTelemetry を有効にします。	false

各上流サービスのベース URL は、ミラーを参照するように設定することもできます：RCSB_SEARCH_BASE_URL、RCSB_DATA_BASE_URL、RCSB_FILES_BASE_URL、RCSB_MODELS_BASE_URL、RCSB_ALIGNMENT_BASE_URL、BEACONS_BASE_URL、ALPHAFOLD_BASE_URL、MODELARCHIVE_BASE_URL、FOLDSEEK_BASE_URL、UNIPROT_BASE_URL、INTERPRO_BASE_URL。デフォルト値と任意のオーバーライドの全一覧については、.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 protein-mcp-server .
docker run --rm -p 3010:3010 protein-mcp-server

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

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリポイントです。ツールとリソースを登録し、プロバイダーサービスを初期化します。
src/config	Zod による、サーバー固有の環境変数の解析と検証を行います。
src/mcp-server/tools	ツール定義（*.tool.ts）と共有スキーマ（_schemas.ts）。
src/mcp-server/resources	リソース定義（*.resource.ts）。
src/services	上流クライアント：rcsb/（検索、データ、ファセット）、alphafold/、beacons/（3D-Beacons）、uniprot/（UniProt、InterPro、GO）、alignment/（RCSB Structural Comparison）、foldseek/、および共有の HTTP、並行処理、識別子、帰属表示用ヘルパーを含む shared/。
tests/	src/ の構成を反映した単体テストと統合テスト。

開発ガイド

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

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

上流データのライセンス

構造データとアノテーションデータは、それぞれ独自のライセンスが適用される公開データベースから取得しています。protein_get_structure と protein_get_annotations は、レスポンスに寄与したすべてのソースについて、ライセンス、引用情報、ホームページを含む attribution ブロックを返します。CC BY および CC BY-SA のソースを再配布する場合は、帰属表示が必要です。CC0 のソースでは、引用のみが求められます。

ソース	寄与先	ライセンス
RCSB PDB	protein_get_structure — 実験記録	CC0 1.0 Universal
AlphaFold DB	protein_get_structure — 予測モデル	CC BY 4.0
ModelArchive	protein_get_structure — MA_* 計算モデル	CC BY 4.0
SWISS-MODEL	protein_get_structure — best_available モデル	CC BY-SA 4.0
BFVD	protein_get_structure — best_available モデル	CC BY 4.0
UniProt	protein_get_annotations	CC BY 4.0
InterPro	protein_get_annotations — ドメイン／ファミリーデータ	CC0 1.0 Universal
GO	protein_get_annotations — GO 用語	CC BY 4.0

best_available モデルは 3D-Beacons 経由で提供されるため、ブロックにはモデルを実際に提供したプロバイダーが記載されます。キュレーション済みのエントリーを持たないプロバイダーには、推測したライセンスではなく See provider terms が表示されます。InterPro と GO は、寄与した場合に限り、それぞれ個別に記載されます。この表は上流データを対象としています。サーバー自体のコードには別のライセンスが適用されます（ライセンスを参照）。

コントリビューション

Issue は歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

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