interpro-mcp-server

---

概述

通过无需密钥的 EMBL-EBI InterPro API，查询来自 InterPro 及其整合的成员数据库（Pfam、PROSITE、SMART、CDD、PANTHER 等）的蛋白质家族、结构域、重复序列和功能位点。搜索条目、读取完整元数据、将 UniProt 蛋白质或 PDB 条目的链映射到带残基坐标的注释、遍历 Pfam、CDD 和 PIRSF 簇、查找包含某个特征的蛋白质，并扫描原始蛋白质序列。支持通过 STDIO、Streamable HTTP 或上述公共托管端点运行，无需配置凭据；启动新的 InterProScan 任务需要由运维人员设置联系邮箱（参见配置）。

工具

工具	描述
interpro_search_entries	按 GO 注释查找 InterPro 条目，或按文本、条目类型或整合登录号查找 InterPro 条目和成员签名
interpro_get_entry	读取一个条目的描述、层级结构、成员签名、GO 术语、文献、交叉引用、族群成员关系和覆盖计数
interpro_get_protein_domains	将 UniProt 蛋白质的结构域、家族、重复序列和功能位点映射到序列坐标，可选定位到一个残基
interpro_get_clan	读取一个 Pfam、CDD 或 PIRSF 集合，并分页浏览其成员；也可选择读取其关系图
interpro_find_proteins_by_domain	查找包含某条目的 UniProt 蛋白质，默认查找经过审阅的人类蛋白质，也可限定在一个蛋白质组内
interpro_get_structure_domains	将签名映射到一个 PDB 条目的蛋白质链，并显示链编号、作者编号和 UniProt 编号
interpro_scan_sequence	查找原始蛋白质序列中的结构域、家族和位点匹配：对 UniParc 序列使用预计算结果，否则启动 InterProScan 任务
interpro_get_scan_result	读取由 interpro_scan_sequence 启动的 InterProScan 任务状态和匹配结果
interpro_list_reference	解码数据库 slug、条目类型、登录号模式、常见分类群 ID 和当前 InterPro 版本

功能参考

interpro_search_entries _工具

• sourceDatabase（默认值为 interpro），以及可选的 query（1–300 个字符）、entryType、goTerm（GO:0003677 格式）、goCategory（P、F、C）和 integratedInto（一个 IPR 登录号，仅适用于成员数据库）；无需任何筛选条件，因此省略所有条件即可浏览数据库
• goTerm 和 goCategory 要求 sourceDatabase: "interpro"；每次调用只能选择一个 GO 筛选条件。组合使用会在访问网络前失败，因为上游在提供术语时会忽略类别。要查找成员签名，请使用 GO 筛选条件搜索 InterPro，然后通过 interpro_get_entry 读取 member_databases，或在 integratedInto 设为匹配的 InterPro 登录号后搜索成员数据库
• 支持游标分页；limit 必须为正整数，最大值为 100（默认值为 20）；超出上限的请求会被截断并附带提示。返回 entries、page（total、returned、limit、hasMore、nextCursor）和已应用的 query；page.limit 是实际页面大小

---

interpro_get_entry _工具

• 必填 accession；省略 sourceDatabase 时会根据标准登录号前缀推断。集合登录号（CL…）会以 entry_not_found 失败，并提示使用 interpro_get_clan
• 可选的 sections 可从 description、hierarchy、member_databases、go_terms、literature、cross_references、wikipedia、counters 和 overlaps_with 中选择。保留核心元数据和未知的上游字段；省略 sections 时返回完整详情
• 可选的正整数 overlapLimit 用于对完整的 overlaps_with 记录分页；overlapOffset 需要同时提供 overlapLimit，从 0 开始，并通过 overlapsPage.nextOffset 推进分页。分页要求保留重叠数据。响应会说明所选内容和省略内容；缺失或为 null 的重叠数据与空列表会加以区分
• 除非设置 includeThumbnail: true，否则会省略 Wikipedia 缩略图，并通过提示说明省略了哪些内容
• entry.descriptionText 会在未经更改的源字段 entry.description 旁添加易读文本，其中保留段落、列表和表格边界，以及 HTML 和注释标记。若排除了描述或未提供可读文本，则省略该字段
• 已撤回的记录会以 entry_withdrawn 失败，并提供删除日期和简称

interpro_get_protein_domains _工具

• 标准的 6 位或 10 位 UniProt accession（不带异构体后缀）；可选的 residuePosition（从 1 开始，包含端点）会保留所有覆盖该位置的片段所对应的匹配项，并保留该匹配项的所有片段；includeExtraFeatures 会添加无序区和跨膜区等预测特征
• includeResidueAnnotations: true 会添加 residueAnnotations，即提供方的功能规则注释。残基筛选会保留任何片段覆盖该位置的完整规则，并保留描述、残基字母、位置和来源信息
• 大型映射会按完整记录分段返回，每个响应的上限为 100,000 字节：先返回匹配项，再返回所请求的额外特征，最后返回所请求的残基规则。持续跟进 coverage.nextCursor，直到 hasMore 为 false。第一个分段包含蛋白质元数据；空分段无法说明没有任何注释。到达相应阶段之前，不会返回残基注释；{} 则表示该阶段未返回任何符合条件的规则
• 不连续片段、模型和上游评分会按原样保留；residue_out_of_range 和 protein_not_found 是带类型的错误

---

interpro_get_clan _工具

• accession 可用于 Pfam（CL0016）、CDD（cl21453）或 PIRSF（PIRSF000047）集合；根据前缀推断 sourceDatabase（pfam、cdd、pirsf）。成员按 cursor 分页，limit 为正整数，上限为 100（默认值为 20）。超出上限的请求会被限制并附带提示；page.limit 会报告实际生效的数量
• includeRelationships: true 会按适合响应上限的分段添加关系图；将 relationshipsPage.nextOffset 作为 relationshipOffset 传回，该参数需要同时设置 includeRelationships
• includeThumbnail 的行为与 interpro_get_entry 相同；找不到集合时返回 clan_not_found

---

interpro_find_proteins_by_domain _工具

• accession，以及可选的 sourceDatabase；taxonId（NCBI，默认值为 9606）和 reviewedOnly（默认值为 true；false 会涵盖已审核和未审核的蛋白质）会在 query 中回显
• 可选的 isFragment 用于筛选被注释为片段的蛋白质（true），或未被注释为片段的蛋白质（false）；省略此参数则包含两者。false 并不能证明序列完整。显式指定的筛选值会出现在 query 中，跟进游标时必须保持不变
• 可选的 architectureId 接受 interpro_get_protein_domains 返回的 protein.ida_accession：一个 40 位十六进制标识符，会规范化为小写。相等表示提供方的 Pfam 架构分组，并不代表功能等价。跟进游标时必须保持不变
• 按游标分页，limit 为正整数，上限为 50（默认值为 20）；超出上限的请求会被限制并附带提示，page.limit 为实际生效的数量。普通结果会保留蛋白质摘要、匹配条目位置、分类单元谱系，以及原生的 extra_fields.is_fragment 注释；缺失或为 null 的状态仍视为未知。按架构筛选的行会在提供时保留原生的 extra_fields.ida_id，并使用 detailAvailability 区分条目或分类单元详情不可用与实际返回空数组的情况
• 可选的 proteomeId（UP 加 9 位数字，不区分大小写，规范化为大写；例如 interpro_get_protein_domains 中的 protein.proteome）会与其他所有筛选条件一起筛选一个 UniProt 蛋白质组。taxonId 仍然适用，包括默认值 9606；只有当 taxonId 是该蛋白质组所属生物的分类单元或其祖先时，才会返回该蛋白质组中的蛋白质。该值会在 query 中回显；跟进游标时必须保持不变。此时各行会携带上游的 proteomes 数组，架构行还会添加 detailAvailability.proteomes
• 无匹配结果仍算成功，并附带提示，因为 API 对未知条目、未知分类单元、未知蛋白质组和空交集的处理方式相同

---

interpro_get_structure_domains _工具

• 必填 pdbId：四个字符的 PDB ID，例如 1tsr，不区分大小写（accession 可用作别名）；不支持扩展的 pdb_0000… ID。可选参数 chain 将映射限制为一个蛋白质链，区分大小写（A 和 a 不同）；不会列出核酸链
• 每个匹配项都通过 entry 关联其位于 structures 中的链记录。记录包含按链编号的位置信息（start/end，从 1 开始），以及作者编号（auth_start/auth_end，可能为 null 或跳号）、UniProt 编号和链到 UniProt 的残基映射；没有 UniProt 映射的链，其 protein 为 null
• InterPro 每个匹配项最多嵌套 20 条链记录。达到此上限的匹配项会将 chainRecordLimitReached 标记为 true，此时可能有链未返回；设置 chain 可完整读取单条链
• 每个分段都包含完整匹配项，响应预算为 100,000 字节；请继续使用 coverage.nextCursor，直到 hasMore 为 false。第一个分段包含 structure（元数据，包括蛋白质的 chains）
• 仅含 DNA 的条目会成功返回，但没有匹配项并附带提示；未知或已废弃的 ID 会以 structure_not_found 失败；不属于该结构蛋白质链的链会以 chain_not_found 失败，并返回 availableChains

---

interpro_scan_sequence _工具

• 必填 sequence：一个由残基字母组成的蛋白质序列，可在前面加一行 FASTA 标题行（最多 100,000 个字符）。忽略大小写、空格和换行；不接受数字、间隙符号和终止符号（*），也不接受空输入或多条 FASTA 记录
• 已存在于 UniParc 中的序列会立即返回预先计算的匹配项（source: "precalculated"）。其他序列会通过 EBI Job Dispatcher 启动一个 InterProScan 6 任务（source: "interproscan"），通常需要约十分钟，因此新序列通常首次返回的结果为 jobId，状态为 submitted、queued 或 running
• waitSeconds（0-35，默认 30）设置新启动的任务在返回 jobId 前等待的时长。若重复提交仍在运行中的序列，会返回相同的 jobId（按服务进程跟踪）；每个进程最多可有 25 个正在运行的任务，超出后调用会以 rate_limited 失败并返回 retryAfter
• 未设置 INTERPRO_SCAN_EMAIL 时，只能获取预先计算的匹配项；其他序列会以 scan_not_configured 失败（参见配置）。托管端点不会设置此项
• 匹配项是 InterProScan 记录的原样内容，按最早位置排序，位置从 1 开始且包含端点；每个分段包含完整记录，预算为 100,000 字节；请使用相同的 sequence 和 coverage.nextCursor 继续获取。此工具不是只读的：调用可能会启动任务

---

interpro_get_scan_result _工具

• 必填 jobId，即 interpro_scan_sequence 返回的值；waitSeconds（0-35，默认 30）用于等待待处理任务，设为 0 时仅检查一次状态
• 任务完成时返回 status: "finished" 及匹配项；任务排队中或运行中时返回 queued 或 running，且不含匹配项（请稍后再次检查）；已完成的任务还会返回 interproVersion 和 interproscanVersion。大型结果可使用相同的 jobId 和 coverage.nextCursor 继续获取
• 任务和结果在提交七天后过期；未知或已过期的任务会以 scan_not_found 失败，出错结束的任务会以 scan_failed 失败；两者都会指向 interpro_scan_sequence

---

interpro_list_reference _工具

• 必填 topic：databases、entry_types、accession_patterns、taxa 或 release。前四项为本地数据，不会发起网络请求；taxa 列出常见示例，而非所有分类单元
• release 会读取当前 InterPro 版本、日期和各数据库条目数；如果两次上游响应中的版本不一致，则会以 release_changed 失败

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志和可选的 OpenTelemetry 跟踪。

InterPro 专属功能：

• 支持 15 个数据库 slug（interpro、pfam、prosite、profile、smart、cdd、panther、cathgene3d、ssf、ncbifam、hamap、prints、pirsf、sfld、antifam）和 11 种条目类型；根据标准登录号前缀推断条目所属数据库，并在本地拒绝冲突的路由
• 对 InterPro API 设置单个进程级请求节流器，每秒最多向上游请求一次；每次工具调用有 50 秒预算，涵盖节流、重试和所有请求；上游响应大小上限为 4 MiB
• 序列扫描会先通过无需密钥的 Matches API 检查预计算结果，再提交 InterProScan 6 任务；对于重复序列，会复用正在运行的任务
• 使用上游 HTTP/1.1 客户端处理 API 不带响应体的 204 响应，这类响应会被 Node 上的原生 fetch 拒绝
• 稀疏的上游元数据会以 null 或省略的形式传递，不会填充内容

便于 Agent 使用的输出：

• content[] 以紧凑 JSON 形式包含完整输出，并附带索引：每个 URL 都作为链接，每张图片都作为图片呈现，因此只读取一种输出形式的客户端也能获取相同数据
• 不透明游标与其查询绑定；结果不完整时，会通过提示明确指出下一次调用的具体内容
• 类型化失败原因（entry_not_found、invalid_cursor、upstream_rate_limited 等）均配有恢复提示
• 坐标描述的是序列注释，而非致病性或临床意义
• 通过 MCP 以及插件安装包、npm 包和 Docker 镜像发布 interpro-guide Agent 技能（标识符链、门控规则，以及 chain/author/UniProt 编号）

开始使用

连接到托管实例，无需安装：

claude mcp add --transport http interpro-mcp-server https://interpro.caseyjhand.com/mcp

或者在本地运行：

claude mcp add interpro-mcp-server -- npx -y @cyanheads/interpro-mcp-server

对于其他客户端，请将以下内容添加到 MCP 配置文件中：

{
  "mcpServers": {
    "interpro-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/interpro-mcp-server"]
    }
  }
}

无需 API 密钥。有关 Docker 或从源码构建的信息，请参阅运行服务。

配置

InterPro API 无需密钥。服务定义了一个可选变量；以下框架变量是最常设置的变量：

变量	说明	默认值
INTERPRO_SCAN_EMAIL	可选的联系邮箱。EBI Job Dispatcher 要求提供该邮箱才能提交 InterProScan 任务。未设置时，interpro_scan_sequence 仍会返回 UniParc 中已有序列的预计算匹配结果；对于其他序列，则会以 scan_not_configured 失败；interpro_get_scan_result 仍可读取已有任务。服务的所有调用方共享同一个邮箱，EBI 会将其与任务数据一同保留七天。托管端点不会设置此项。	未设置
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_HOST	HTTP 服务主机。	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	HTTP 端点路径。	/mcp
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。启用身份验证后，每个工具都需要对应的 tool:<tool_name>:read 作用域；interpro_scan_sequence 可以启动任务，因此需要 tool:interpro_scan_sequence:write。	none
MCP_LOG_LEVEL	日志级别（debug、info、notice、warning、error）。	info
LOGS_DIR	日志文件目录（仅 Node.js）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false

常见的框架覆盖项请参阅 .env.example。

运行服务

本地开发

需要 Bun v1.4.0 或更高版本（或 Node.js v24+）。

• 克隆并安装：

  git clone https://github.com/cyanheads/interpro-mcp-server.git
  cd interpro-mcp-server && bun install
  cp .env.example .env   # optional; the server needs no keys
  

• 构建并运行：

  # 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 run --rm -p 3010:3010 ghcr.io/cyanheads/interpro-mcp-server:latest

镜像默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/interpro-mcp-server。要通过 MCP 客户端使用 stdio 运行，请使用 "command": "docker" 和 "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/interpro-mcp-server:latest"]。要在本地构建，请运行 docker build -t interpro-mcp-server .；默认会安装 OpenTelemetry 对等依赖项，构建时添加 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点：注册工具并启动 InterPro 和序列扫描服务。
src/config	解析服务器专用环境变量（INTERPRO_SCAN_EMAIL）。
src/mcp-server/tools	工具定义（*.tool.ts）。共 9 个工具。
src/services/interpro	InterPro 服务：HTTP/1.1 适配器、请求节流器和截止时间、登录号路由、游标、架构以及共享结果格式化器。
src/services/sequence-scan	序列解析、预计算查找、InterProScan 作业提交和轮询，以及扫描结果分段。
skills/	已发布的 Agent 技能（interpro-guide），通过 MCP 提供，并随软件包一同发布。
tests/	单元测试和集成测试，结构与 src/ 对应。

开发指南

开发指南和架构规则请参见 CLAUDE.md。简要说明：

• 处理程序抛出异常，框架负责捕获；工具逻辑中不使用 try/catch
• 使用 ctx.log 记录请求级日志
• 在 src/index.ts 的 createApp() 数组中注册新工具
• 封装外部 API 调用：验证原始数据，将其规范化为领域类型，并返回输出架构；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目基于 Apache 2.0 许可证授权。详情请参见 LICENSE 文件。

数据通过 EMBL-EBI API 从 InterPro 及其成员数据库获取。各成员数据库的许可条款有所不同，因此请注明 InterPro 和数据来源数据库；请参见 InterPro 的许可证页面和 EMBL-EBI 使用条款。