RCSB PDB

rcsb-mcp

一个用于查询蛋白质数据库（Protein Data Bank）结构的 MCP 服务，可从 LLM 客户端（Claude Desktop、MCP Inspector、Cursor 等）发现、检查和交叉引用结构。它涵盖三个 RCSB API：

• 发现 — 使用 Search API 查找结构（关键词、属性、序列、化学、3D 形状、基序）。
• 检查 — 从 Data API 获取条目、实体、组装体、配体的详细信息及注释。
• 关联 — 使用 Sequence Coordinates API 映射 PDB、UniProt 和 NCBI 之间的序列及位置特征。

工具

Search (search.rcsb.org)

搜索分为两个步骤：先用 rcsb_query_* 工具构建查询，再用 rcsb_search_request 执行。构建器是纯函数——它们返回查询文档（可读的 JSON 加上摘要），不会访问网络，因此只有调用 rcsb_search_request 后才会执行搜索。rcsb_query_composer 可通过 AND/OR 合并两个或更多文档， 这也是在单次搜索中组合不同服务的方式（例如，序列相似性 AND 生物体筛选条件）。

构建

工具	功能
rcsb_query_fulltext	自由文本关键词查询（例如，"CRISPR Cas9"）。
rcsb_query_attribute	针对一个或多个索引属性（分辨率、生物体、发布日期等）构建结构化查询，并通过单个 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	通过 AND/OR 合并 2 个或更多查询文档——支持嵌套布尔逻辑，也是单次搜索中组合不同服务的唯一方式。

执行

工具	功能
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 分类体系），并标注 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 的属性，查询的形态决定了语义：在同一次 rcsb_query_attribute 调用中构建且不包含其他内容的条件，必须在同一条记录上成立；分开调用的条件则会分别匹配任意记录。两种方式都有效，但含义不同：type=Kd 与 value<1 描述的是一次测量，而 InterPro ID 和 GO 类型必然属于不同的注释。

计数与分面是 rcsb_search_request 的输出选项，而不是单独的工具： 每个响应都包含 total_count（完整的匹配数量——若想查询“有多少个……”，请将搜索的 limit=1，然后读取该值）；传入 facets 则会返回分类统计（terms/histogram/date_histogram/range/cardinality），而不是命中项。terms 分面还能告诉你命中项共有哪些特征，从而将少量结果转化为可用于再次搜索的取值。

分组。 group_by 会为每个簇返回一个代表项——序列一致性簇使用 seqid_30 … seqid_95，也可以用 uniprot 按登录号合并；group_by_ranking 用于选择代表项。要求 return_type="polymer_entity"； 响应会同时报告 group_count 和 total_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 会在一次调用中返回完整结果集（超过 10,000 条结果时会被拒绝， 且不能与 offset 结合使用）。

数据（data.rcsb.org/graphql）

Data API 的每个 GraphQL 根字段都有一个对应的工具。每个工具都接受一个ID 列表 （单条查询时传入一个仅含单个元素的列表），以及可选的 fields 参数，用你自己的 GraphQL 子选择 覆盖经过整理的默认选择。未知 ID 会在 not_found 下报告。使用 rcsb_describe_data_object 查找应填入 fields 的路径 — 浏览某一层级，使用 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= 按关键字搜索（扁平结果，包含嵌套路径和跨对象路径）。返回经过验证的点分隔路径。它是 Data API 版的 rcsb_list_pdb_search_attributes。	—

Search API 只返回标识符，因此搜索是第一步：将返回的 ID 分批传给匹配的 rcsb_get_* 工具，以获取标题、物种 和其他元数据（这些工具会查询 GraphQL 端点，并将所有请求的 ID 批量放入一个请求中）。全部 16 个类型化工具都由 queries.py（DATA_OBJECTS）中的单个注册表生成，因此添加字段或端点只需 修改一行。

序列坐标（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 结构？”这个问题应使用 rcsb_seqcoord_alignments，而不是 Data API。PDB 查询 ID 必须是实体级别（4HHB_1），不能是单独的条目（4HHB）；若要查询整个条目，请分别查询其中的每个聚合物实体。

工具	功能
rcsb_seqcoord_alignments	在 PDB／UniProt／NCBI 之间交叉引用序列，并提供比对范围（例如，4HHB_1 → NCBI 蛋白质 NP_000508、NP_000549）。
rcsb_seqcoord_annotations	获取 PDB 实体或实例（7CUT_1、4HHB.A）的位置特征，来源包括 UniProt、该实体、其各个实例及其界面；也可选择仅获取部分 feature_types（ACTIVE_SITE），具体来源由类型决定。
rcsb_describe_seqcoord_object	检查实时架构，以了解序列坐标对象上有哪些字段可用（供 fields= 使用）。

报告

工具	功能
rcsb_render_report	将搜索结果的结构化报告（标题、列、行和证据）渲染为格式化的 HTML 文档，供用户查看。

安装

RCSB 托管了该服务，因此大多数客户端无需安装——只需将其指向 https://mcp-beta.rcsb.org/mcp（参见连接 Agent）。只有在需要自行运行、固定版本或基于该项目进行开发时，才需要安装：

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

rcsb-mcp 已作为 io.github.rcsb/rcsb-mcp 列入 Official MCP Registry，因此支持注册表的客户端可以直接发现它。

如需进行本地开发，请改为从项目根目录安装：

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/）：rcsb_pdb_eval.xml 包含 14 个只读的稳定问题，用于衡量大模型使用这些工具回答真实 PDB 问题的能力；evals/tool_selection/ 是一个首次工具调用 A/B 测试框架，用于在编辑文档字符串后发现路由回归。参阅evals/README.md以运行其中任一套件。

连接 Agent

托管版（Beta）

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 客户端不受影响。

Beta。 端点、工具集和工具描述可能会在不另行通知的情况下发生变化，且不保证稳定性——如果需要固定的工具集，请固定 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
• “哪些结构的 3D 折叠与 4HHB 类似？” → 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）
• “按实验方法／发布日期统计核糖体结构。” → 在 rcsb_search_request 中使用 facets
• “查找催化位点几何形状与 2MNR 的 162／193／219 位残基相同的结构。” → rcsb_query_strucmotif → rcsb_search_request
• “查找小于 150 Da 的化学组分。” → rcsb_list_pdb_search_attributes(schema="chemical") → 使用 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
• “哪些 PDB 实体与 UniProt P69905 比对，对应范围是什么？” → rcsb_seqcoord_alignments
• “哪些 NCBI 蛋白质对应 4HHB？” → 对每个实体（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 查找路径，然后调用对应的 rcsb_get_* 工具并设置 fields=

说明

• 搜索端点：https://search.rcsb.org/rcsbsearch/v2/query（POST，JSON 正文）。
• 数据端点：https://data.rcsb.org/graphql（POST，GraphQL）。即使查询出错，它也会返回 HTTP 200，并在 errors 数组中报告错误。
• 序列坐标端点：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 可覆盖此值（其中的 {version} 会以相同方式填入）；Helm 图表会设置该变量，因此上游日志可以区分托管服务的流量和本地安装的流量。
• rcsb_query_attribute 的可搜索属性完整列表见 Search API 属性参考； Data API 架构文档见 data.rcsb.org/index.html#gql-api。

提示词

服务器提供一个 MCP 提示词 rcsb_search_assistant（“RCSB PDB 搜索助手”）——其中包含搜索要求和 HTML 报告输出格式。由于它通过协议的 prompts 能力提供，任何 MCP 客户端都可以列出并调用它（Claude Desktop 会在 + / 提示词菜单中显示服务器提示词）；无需复制粘贴。文本位于 src/rcsb_mcp/prompts/rcsb_search_assistant.md， 并随软件包一同发布。

当你希望答案采用 PDB 报告格式时，请调用它。它并非工具正常工作的必要条件：所有路由规则、注意事项和交叉引用都写在工具描述本身中，协议始终会传递这些描述。这些指导内容过去还放在另外两个位置，但这两处现已弃用：服务器的 instructions 块（客户端可能会截断或丢弃它）以及第二个 rcsb_mcp_guide 提示词（需选择启用，因此可能永远不会加载）。现在，instructions 只简要介绍各工具系列，供那些在加载工具描述前就显示工具名称的客户端使用；其中每一行都重述了工具描述，且没有任何内容是使用工具所必需的。 prompts/rcsb_mcp_guide.md 保留在磁盘上，不对外提供，作为提取原文的来源。