RCSB PDB

rcsb-mcp

LLM クライアント（Claude Desktop、MCP Inspector、Cursor など）から、Protein Data Bank の構造を検索、調査、相互参照するためのMCP サーバーです。3 つの RCSB API を利用します。

• 検索 — Search APIで構造を検索します（キーワード、属性、配列、化学、3D 形状、モチーフ）。
• 調査 — Data APIからエントリー／エンティティ／アセンブリ／リガンドの詳細情報と注釈を取得します。
• 関連付け — Sequence Coordinates APIを使って、PDB、UniProt、NCBI 間で配列と位置情報の特徴を対応付けます。

ツール

検索（search.rcsb.org）

検索は2 段階で行います。まず rcsb_query_* ツールでクエリを作成し、次に rcsb_search_request で実行します。ビルダーは純粋関数で、クエリドキュメント（読みやすい JSON とダイジェスト）を返し、ネットワークにはアクセスしません。そのため、rcsb_search_request を呼び出すまで検索は実行されません。rcsb_query_composer は 2 つ以上のドキュメントを AND/OR で結合します。これにより、1 回の検索で複数のサービスを組み合わせることもできます（例：配列類似性 AND 生物種フィルター）。

作成

ツール	説明
rcsb_query_fulltext	フリーテキストのキーワードクエリ（例："CRISPR Cas9"）。
rcsb_query_attribute	1 つ以上のインデックス付き属性（分解能、生物種、公開日など）を対象とする構造化クエリ。単一の logical_operator で結合します。各条件は exists、negation、case_sensitive に対応し、chemical_attributes=True を指定すると化学成分カタログが選択されます。
rcsb_query_sequence	MMseqs2 による配列類似性クエリ（BLAST に類似）。同一性／e-value のしきい値を指定できます。
rcsb_query_chemical	SMILES/InChI 記述子（分子全体または部分構造）または分子式による化学クエリ。
rcsb_query_structure	参照 PDB アセンブリまたはチェーンに対する 3D 形状類似性クエリ。
rcsb_query_seqmotif	短い配列モチーフクエリ（PROSITE パターン、正規表現、または単純なワイルドカード）。
rcsb_query_strucmotif	3D 構造モチーフクエリ：特定の残基の幾何学的配置（例：触媒三残基）。
rcsb_query_composer	2 つ以上のクエリドキュメントを AND/OR で結合します。ネストしたブール論理に対応し、1 回の検索で異なるサービスを組み合わせる唯一の方法です。

実行

ツール	説明
rcsb_search_request	クエリドキュメントを実行し、一致する識別子のみを返します。すべての出力オプションを指定します：return_type、limit/offset、all_hits、facets、sort_by/sort_direction、group_by/group_by_ranking、include_computed_models。

検索

ツール	機能
rcsb_list_pdb_search_attributes	検索可能な属性パス、型、演算子を確認します。schema="structure"（デフォルト、約636件）または schema="chemical"（約58件：chem_comp.*、drugbank_info.* など）を指定できます。レコードには enum（固定の値セット）と nested_group（ネストされたオブジェクトに格納されている属性。以下を参照）も含まれます。
rcsb_find_go_terms	フリーテキストで指定した分子機能／生物学的プロセス／細胞構成要素をGene OntologyのIDに解決し（EBI QuickGO経由）、PDBエントリー数を付与します。その後、rcsb_polymer_entity_annotation.annotation_lineage.id で検索します。
rcsb_find_interpro_domains	フリーテキストで指定したタンパク質ドメイン／ファミリー／フォールドをInterProおよびPfamのIDに解決し（EBI Search経由）、PDBエントリー数を付与します。その後、rcsb_polymer_entity_annotation.annotation_id で検索します。
rcsb_find_enzyme_classes	フリーテキストで指定した酵素／反応をEnzyme Commission（EC）番号に解決し（EBI Search／IntEnz経由）、PDBエントリー数を付与します。その後、rcsb_polymer_entity.rcsb_ec_lineage.id で検索します（階層型）。
rcsb_find_disease_terms	フリーテキストで指定した疾患／状態をMONDOのIDに解決し（EBI OLS経由）、PDBエントリー数を付与します。その後、rcsb_uniprot_annotation.annotation_lineage.id で検索します（階層型、UniProtベース）。
rcsb_find_organisms	フリーテキストで指定した生物／一般名／クレードをNCBI TaxonomyのIDに解決し（UniProt taxonomy経由）、PDBエントリー数を付与します。その後、rcsb_entity_source_organism.taxonomy_lineage.id で検索します（階層型：クレードIDはその配下のすべての生物に一致します）。

どちらの属性カタログも、稼働中のメタデータスキーマから scripts/generate_search_attributes.py によって生成されます。化学成分の属性を検索するには、 rcsb_list_pdb_search_attributes(schema="chemical") でパスを確認し、rcsb_query_attribute に chemical_attributes=True を渡し、通常は return_type="mol_definition" を設定します。

ネストされた属性。 オブジェクトには、多数のアノテーション、結合親和性、引用情報が含まれる場合があります。nested_group を持つ属性では、クエリの形によって意味が決まります。条件を1回の rcsb_query_attribute 呼び出しにまとめ、その中にほかの条件を含めない場合、条件は同じレコードに適用されます。別々の呼び出しに分けた条件は、それぞれ任意のレコードと独立して照合されます。どちらも有効ですが、意味は異なります。type=Kd と value<1 は1つの測定値を表しますが、InterProのIDとGOの型は必ず別々のアノテーションです。

件数とファセットは rcsb_search_request の出力オプションであり、独立したツールではありません。すべてのレスポンスに total_count（一致する全件数）が含まれます。「いくつあるか」を確認するには、検索時に limit=1 を指定して、この値を読み取ります。facets を渡すと、ヒットの代わりに内訳（terms／histogram／date_histogram／range／cardinality）が返されます。termsファセットでは、ヒットに共通する内容も確認できるため、少数の検索結果から再検索可能な値を得られます。

グループ化。 group_by は各クラスターの代表を1件ずつ返します。配列同一性クラスターには seqid_30 ～ seqid_95、アクセッションでまとめるには uniprot を指定し、代表の選択には group_by_ranking を使用します。return_type="polymer_entity" が必要です。レスポンスでは total_count とともに group_count も報告されます。

並べ替え。 sort_by（属性パス）と sort_direction（asc／desc）を指定すると、デフォルトのスコア順が置き換わります（類似性検索では、類似度順がこの指定で上書きされます）。並べ替えに対応しているのは、rcsb_list_pdb_search_attributes で exact_match（文字列）または equals（数値／日付）が公開されている属性のみです。return_type="mol_definition" では並べ替えを利用できません。 ページング。 rcsb_search_request は limit（1～100、デフォルトは10）と offset（デフォルトは0）を受け付けます。各レスポンスには total_count、has_more、next_offset が含まれます。同じクエリドキュメントを使い、offset=next_offset を指定して再度呼び出してください。明示的な「ALL ...」リクエストでは、all_hits=True を指定すると1回の呼び出しで全件を取得できます（10,000件を超える場合は拒否され、offset と併用することはできません）。

Data（data.rcsb.org/graphql）

Data API の GraphQL ルートフィールドごとにツールが1つあります。各ツールは ID のリスト（単一の検索では1要素のリスト）と、独自の GraphQL サブセレクションでキュレーション済みのデフォルト選択を上書きするための省略可能な fields 引数を受け取ります。不明な ID は not_found に報告されます。fields に指定するパスは rcsb_describe_data_object で確認できます。階層を参照したり、into= でネストされたオブジェクトを掘り下げたり、query= と max_depth= を使ってキーワードでスキーマを検索したりできます。返される各パスはライブスキーマに対して検証済みなので、フィールド名を推測しないでください。

ツール	オブジェクト	ID の例
rcsb_get_entries	PDB エントリー	"4HHB"
rcsb_get_polymer_entities	ポリマーエンティティ（タンパク質／NA）	"4HHB_1"
rcsb_get_nonpolymer_entities	非ポリマーエンティティ（リガンド／補因子）	"4HHB_3"
rcsb_get_branched_entities	糖質エンティティ	"5FMB_2"
rcsb_get_polymer_entity_instances	ポリマーチェーン	"4HHB.A"
rcsb_get_nonpolymer_entity_instances	結合リガンドインスタンス	"4HHB.E"
rcsb_get_branched_entity_instances	糖鎖	"5FMB.C"
rcsb_get_assemblies	生物学的アセンブリ	"4HHB-1"
rcsb_get_interfaces	アセンブリインターフェース	"1BMV-1.1"
rcsb_get_chem_comps	化学成分／リガンド	"HEM"、"ATP"
rcsb_get_entry_groups	エントリーグループ	"G_1002266"
rcsb_get_polymer_entity_groups	ポリマーエンティティグループ（配列クラスター）	"85_70"
rcsb_get_nonpolymer_entity_groups	非ポリマーエンティティグループ	"ATP"
rcsb_get_uniprot	UniProt レコード（単一）	"P69905"
rcsb_get_pubmed	PubMed レコード（単一、整数）	6726807
rcsb_get_group_provenance	グループ化のプロベナンス（単一）	"provenance_sequence_identity"
rcsb_describe_data_object	オブジェクトのライブ GraphQL スキーマをイントロスペクションし、fields= 選択を作成します。階層を参照したり、into= でネストされたオブジェクトを掘り下げたり、query= と max_depth= を使ってキーワードで検索したりできます（フラット形式で、ネストおよびオブジェクト間のパスを含みます）。検証済みのドット区切りパスを返します。rcsb_list_pdb_search_attributes に相当する Data API のツールです。	—

Search API が返すのは識別子のみなので、検索は最初のステップです。返された ID を対応する rcsb_get_* ツールにまとめて渡し、タイトル、生物種、その他のメタデータを取得します（これらのツールは GraphQL エンドポイントにクエリを送信し、リクエストされたすべての ID を1つのリクエストにまとめます）。16個の型付きツールはすべて、queries.py（DATA_OBJECTS）の単一レジストリから生成されるため、フィールドやエンドポイントの追加は1行の変更で済みます。

シーケンス座標（sequence-coordinates.rcsb.org/graphql）

配列のアラインメントと位置アノテーションを、複数の配列参照システム （UNIPROT、NCBI_PROTEIN、NCBI_GENOME、PDB_ENTITY、PDB_INSTANCE）間で対応付けます。各 ツールでは、デフォルトの選択項目を上書きする任意のfields引数を指定できます。利用可能なフィールドを確認するには、 rcsb_describe_seqcoord_objectを使用します。

NCBI（RefSeqタンパク質／ゲノム）を相互参照するRCSB APIはこれだけです。Data APIが認識するのはUniProtのみです。そのため、「どのNCBIタンパク質がPDB構造に対応するか？」という質問には、Data APIではなくrcsb_seqcoord_alignmentsで回答します。PDBクエリIDは、単独のエントリー（4HHB）ではなく、エンティティレベル（4HHB_1）で指定する必要があります。エントリー全体を調べるには、ポリマーエンティティごとにクエリしてください。

ツール	機能
rcsb_seqcoord_alignments	PDB／UniProt／NCBI間の配列を、アラインメント範囲とともに相互参照します（例：4HHB_1 → NCBIタンパク質 NP_000508、NP_000549）。
rcsb_seqcoord_annotations	UniProt、エンティティ、そのインスタンスおよびインターフェースから、PDBエンティティまたはインスタンス（7CUT_1、4HHB.A）の位置的特徴を取得します。必要に応じて、特定のfeature_types（ACTIVE_SITE）のみに絞り込めます。取得元は特徴の種類によって決まります。
rcsb_describe_seqcoord_object	ライブスキーマを調べて、seqcoordオブジェクトで利用可能なフィールドを確認します（fields=で使用）。

レポート

ツール	機能
rcsb_render_report	検索結果を構造化レポート（タイトル、列、行、根拠）としてレンダリングし、ユーザー向けに整形されたHTMLドキュメントにします。

インストール

RCSBがサーバーをホストしているため、ほとんどのクライアントはインストール不要です。https://mcp-beta.rcsb.org/mcpを指定してください（エージェントを接続するを参照）。自分で実行する場合、バージョンを固定する場合、または開発用に使用する場合にのみインストールしてください。

# run the published package without installing
uvx rcsb-mcp
# or install it
pip install rcsb-mcp

rcsb-mcpは公式MCPレジストリにio.github.rcsb/rcsb-mcpとして登録されているため、レジストリ対応クライアントから直接検出できます。

ローカルで開発する場合は、代わりにプロジェクトのルートからインストールしてください。

pip install -e .
# or with uv
uv pip install -e .

実行／テスト

# unit tests (no network)
hatch test          # or: python tests/test_queries.py

# run the server over stdio
python -m rcsb_mcp.server
# or, after install:
rcsb-mcp

# inspect interactively
npx @modelcontextprotocol/inspector python -m rcsb_mcp.server

評価スイート（evals/）は2つあります。rcsb_pdb_eval.xmlは、LLMがこれらのツールを使って実際のPDBに関する質問にどれだけ回答できるかを測定する、読み取り専用の安定した14個の質問です。もう一つのevals/tool_selection/は、docstringの編集後にルーティングのリグレッションを検出するための、最初のツール呼び出しを比較するA/Bハーネスです。どちらかを実行する方法については、evals/README.mdを参照してください。

エージェントを接続する

ホスト型（ベータ版）

https://mcp-beta.rcsb.org/mcp

Streamable HTTPで、インストール不要、APIキー不要、アカウント不要です。デプロイはステートレスです。どのレプリカも任意のリクエストに応答するため、セッションヘッダーは不要で、呼び出しの間に接続を維持する必要もありません。ローカル実行と同じ36個のツールとrcsb_search_assistantプロンプトを提供します。

Claude Code

claude mcp add --transport http rcsb-mcp https://mcp-beta.rcsb.org/mcp

Claude Desktop — Settings → Connectors → Add custom connectorを選択し、URLを貼り付けます。

URLを指定するクライアント全般（.mcp.json、Cursor、VS Code、Zedなど）：

{
  "mcpServers": {
    "rcsb-mcp": {
      "type": "http",
      "url": "https://mcp-beta.rcsb.org/mcp"
    }
  }
}

Stdioのみ対応のクライアントは、mcp-remoteを使ってブリッジできます。

{
  "mcpServers": {
    "rcsb-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp-beta.rcsb.org/mcp"]
    }
  }
}

手動で確認する — initializeだけなら、セッションのセットアップは不要です。

curl -s https://mcp-beta.rcsb.org/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2025-06-18","capabilities":{},
        "clientInfo":{"name":"curl","version":"0"}}}'

GET /healthzは、生存確認チェックに対して200を返します。エンドポイント（またはサイトのルート）をウェブブラウザーで開くと、クライアントの接続方法を説明する短いページが表示されます。MCPクライアントへの影響はありません。

ベータ版。 エンドポイント、ツールの種類、ツールの説明は予告なく変更される場合があり、安定性も保証されません。固定された仕様が必要な場合は、uvx rcsb-mcp==<version>でバージョンを固定し、自分で実行してください。問題を報告する際は、ビルドを特定できるよう、initializeの応答に含まれるserverInfo.versionを記載してください。

ローカル（stdio）

開発時や特定のバージョンに固定したい場合は、代わりにサーバーをサブプロセスとして実行します。

claude_desktop_config.jsonを編集します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "rcsb-mcp": {
      "command": "uvx",
      "args": ["rcsb-mcp"]
    }
  }
}

ローカルのソースチェックアウトを使用する場合は、代わりにモジュールを指定します。

{
  "mcpServers": {
    "rcsb-mcp": {
      "command": "python",
      "args": ["-m", "rcsb_mcp.server"],
      "cwd": "/absolute/path/to/rcsb-mcp/src"
    }
  }
}

Claude Desktopを再起動します。コネクター（プラグ）アイコンの下にツールが表示されます。

プロンプトの例

• 「高解像度のヒトヘモグロビン構造を検索してください。」→ rcsb_query_fulltext + rcsb_query_attribute → rcsb_query_composer → rcsb_search_request
• 「分解能が2 Åより高いヒトヘモグロビン構造を、最良の分解能から順に表示してください。」→ 同じ手順で、rcsb_search_requestにsort_byを指定します
• 「次のタンパク質配列に一致するPDBエントリーを教えてください：MTEY...」→ rcsb_query_sequence → rcsb_search_request
• 「このSMILESに似たリガンド、または分子式C8H9NO2を持つ構造を検索してください。」→ rcsb_query_chemical → rcsb_search_request
• 「4HHBに似た3Dフォールドを持つ構造を教えてください。」→ rcsb_query_structure → rcsb_search_request
• 「ジンクフィンガーモチーフを持つタンパク質を検索してください。」→ rcsb_query_seqmotif → rcsb_search_request
• 「キナーゼ活性を持つ／DNA修復に関与する／ミトコンドリア膜に存在するタンパク質の構造を検索してください。」→ rcsb_find_go_terms → rcsb_polymer_entity_annotation.annotation_lineage.idに対するrcsb_query_attribute
• 「SH2ドメイン／免疫グロブリンフォールドを含む構造を検索してください。」→ rcsb_find_interpro_domains → rcsb_polymer_entity_annotation.annotation_idに対するrcsb_query_attribute
• 「アルコールデヒドロゲナーゼの構造／EC 3.4.21のセリンプロテアーゼを検索してください。」→ rcsb_find_enzyme_classes → rcsb_polymer_entity.rcsb_ec_lineage.idに対するrcsb_query_attribute
• 「嚢胞性線維症／乳がんに関連するタンパク質の構造を検索してください。」→ rcsb_find_disease_terms → rcsb_uniprot_annotation.annotation_lineage.idに対するrcsb_query_attribute
• 「哺乳類／特定の生物種または分類群に由来する構造を検索してください。」→ rcsb_find_organisms → rcsb_entity_source_organism.taxonomy_lineage.idに対するrcsb_query_attribute
• 「重複を除いたヒトキナーゼ構造（配列同一性90％のクラスター）を検索してください。」→ group_by="seqid_90"、return_type="polymer_entity"を指定したrcsb_search_request
• 「ヒトのX線構造はいくつありますか？」→ rcsb_query_attribute → limit=1を指定したrcsb_search_request（total_countを読み取ります）
• 「リボソーム構造を実験手法別／公開年別に分類してください。」→ facetsを指定したrcsb_search_request
• 「2MNRの残基162／193／219と同じ触媒部位の構造を検索してください。」→ rcsb_query_strucmotif → rcsb_search_request
• 「150 Da未満の化学成分を検索してください。」→ schema="chemical"を指定したrcsb_list_pdb_search_attributes → chemical_attributes=Trueを指定したrcsb_query_attribute → return_type="mol_definition"を指定したrcsb_search_request
• 「PDBエントリー4HHB、1MBN、6VXXを要約してください。」→ rcsb_get_entries
• 「エンティティ4HHB_1の配列と生物種を教えてください。」→ rcsb_get_polymer_entities
• 「リガンドHEMについて教えてください。」→ rcsb_get_chem_comps
• 「4HHBの生物学的アセンブリーの組成を教えてください。」→ rcsb_get_assemblies
• 「P69905に対応するPDBエントリーを教えてください。」→ rcsb_get_uniprot
• 「UniProt P69905にアラインメントされるPDBエンティティと、その範囲を教えてください。」→ rcsb_seqcoord_alignments
• 「4HHBに対応するNCBIタンパク質を教えてください。」→ 各エンティティ（4HHB_1、4HHB_2）についてrcsb_seqcoord_alignmentsを実行し、to_ref=NCBI_PROTEINを指定します
• 「PDBエンティティ4HHB_1に対応する結合部位を教えてください。」→ feature_types=["BINDING_SITE"]を指定したrcsb_seqcoord_annotations
• 「簡潔なデフォルト設定に含まれないフィールドを取得してください。」→ rcsb_describe_data_objectでパスを確認してから、fields=を指定して対応するrcsb_get_*ツールを実行します

注意事項

• 検索エンドポイント：https://search.rcsb.org/rcsbsearch/v2/query（POST、JSON ボディ）。
• データエンドポイント：https://data.rcsb.org/graphql（POST、GraphQL）。クエリエラーが発生しても HTTP 200 を返し、errors 配列にエラーを報告します。
• Sequence Coordinates エンドポイント：https://sequence-coordinates.rcsb.org/graphql （POST、GraphQL。HTTP 200 と errors を返す動作は同じです）。
• rcsb_find_* リゾルバーは、EBI サービスを介してフリーテキストをオントロジー ID に対応付けます。RCSB 以外の依存先は、QuickGO 経由の GO（.../QuickGO/services/ontology/go/search）、EBI Search 経由の InterPro と Pfam（.../ebisearch/ws/rest/interpro7）、EBI Search／IntEnz 経由の EC（.../ebisearch/ws/rest/intenz）、OLS／MONDO 経由の疾患（.../ols4/api/search?ontology=mondo）、UniProt 経由の生物種（.../rest.uniprot.org/taxonomy/search）です。解決された ID は、その後の RCSB アノテーション検索（rcsb_polymer_entity_annotation.*、rcsb_polymer_entity.rcsb_ec_lineage.id、rcsb_uniprot_annotation.annotation_lineage.id）に使用されます。
• API キーは不要です。API は公開されています。リクエスト量にはご配慮ください。
• すべての送信リクエストには、User-Agent: rcsb-mcp/<version> (https://github.com/rcsb/rcsb-mcp) が設定されます。<version> はインストール済みパッケージのバージョン（pyproject.toml の値）です。RCSB_MCP_USER_AGENT を設定すると上書きできます（表示可能な ASCII 文字を使用してください。値に含まれる {version} は同様に置換されます）。Helm チャートではこの設定を行うため、ホスト型サービスのトラフィックを上流のログでローカルインストールと区別できます。
• rcsb_query_attribute で検索できる属性の全リストは、Search API の属性リファレンスを参照してください。Data API のスキーマは data.rcsb.org/index.html#gql-apiに記載されています。

プロンプト

サーバーは、MCP プロンプト rcsb_search_assistant（「RCSB PDB 検索アシスタント」）を 1 つ公開します。検索要件と HTML レポートの出力形式が含まれています。これはプロトコルの prompts 機能を通じて提供されるため、どの MCP クライアントからでも一覧表示して呼び出せます（Claude Desktop では、サーバーのプロンプトが +／プロンプトメニューに表示されます）。コピー＆ペーストは不要です。テキストは src/rcsb_mcp/prompts/rcsb_search_assistant.md にあり、パッケージに同梱されています。

PDB レポート形式で回答してほしい場合に呼び出してください。ツールの動作に必須ではありません。ルーティング規則、注意点、相互参照はすべて各ツールの説明に記載されており、プロトコルによって常にクライアントに提供されます。このガイダンスは以前、ほかの 2 か所に記載されていましたが、どちらも廃止されています。サーバーの instructions ブロック（クライアントが切り詰めたり削除したりするため）と、2 つ目の rcsb_mcp_guide プロンプト（任意で読み込むため、読み込まれない場合があります）です。現在、instructions にはツールの説明を読み込む前にツール名を表示するクライアント向けに、ツールの種類を簡潔に示す案内のみが記載されています。各行はツールの説明を言い換えたものであり、ツールの使用に不可欠な情報は含まれていません。 prompts/rcsb_mcp_guide.md は、文章を復元するための資料として、ディスク上に残されていますが、提供はされません。