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}	根据 accession 获取经过整理的 UniProtKB 条目——这是单个 accession 对应的 uniprot_get_entry 资源镜像。
uniprot://taxonomy/{taxonId}	根据 NCBI taxon ID 获取分类记录——包括名称、等级、父级和完整谱系。这是按 ID 查询 uniprot_get_taxonomy 的镜像。

所有资源数据也都可以通过工具访问——仅使用工具的客户端不会遗漏任何内容。UniProtKB 规模过大，无法枚举，因此没有资源 list()；发现条目由 uniprot_search_proteins 负责。

提示词

提示词	描述
uniprot_protein_dossier	引导式蛋白质研究工作流——解析标识符、获取经过整理的条目、提取疾病和变异信息，并展示结构、引文和生物活性的交叉引用。

能力参考

uniprot_search_proteins _工具

• text_search 用于自然语言查询，或 query 用于 Lucene 字段语法（gene、organism_id、keyword、go、reviewed、protein_name、family、length、existence、accession）——二者必须且只能选择一个。organism_id 会筛选整个查询；不匹配的括号会被拒绝。可选的 facets 会返回计数明细（例如 reviewed、model_organism）
• reviewed 默认为 true（仅搜索 Swiss-Prot）；false 则搜索两个层级（在 query 中设置 reviewed:false 可仅搜索 TrEMBL）。每条命中结果都包含 reviewed、annotationScore 和 proteinExistence
• 仅支持向前的游标分页；返回 totalResults 和实际使用的查询。游标绑定到此工具以及组装后的确切查询，包括 organism/reviewed 筛选条件。更改 size、fields 或 facets 后，继续分页仍然有效；如果查询发生变化、令牌格式错误或使用旧版原始游标，则会返回 invalid_cursor：请不带游标重新开始
• 非活跃 accession（已合并、拆分或删除）会连同原因和替代项放入 inactive[]，而不是 results[]

---

uniprot_get_entry _工具

• 每次调用最多可查询 20 个 accession，来源可以是 uniprot_search_proteins 或 uniprot_map_ids（去掉任何 -N 亚型后缀）。记录按章节组织：功能、催化活性、辅因子、亚细胞定位、疾病、PTM、天然变异、亚型、结构域、GO 术语、关键词和交叉引用。fields 可精简输出；身份和来源字段始终保留
• 已解析的条目会放入 succeeded[]，未知或非活跃的条目会放入 failed[]，因此单个错误的 accession 不会导致整个批次中止。非活跃 accession 的错误信息会指出合并目标、拆分后条目或 UniParc ID
• 如果初始响应中 content[] 和 structuredContent 的 UTF-8 字节总数超过 24,000，则会返回 kind: "outline"。单个已解析的 accession 会返回章节列表；超出大小限制的批次会按请求顺序返回 outlinedEntries，并保留每个 failed[] 条目。逐个重新调用每个列出的 accession，然后使用 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" 和一个 ticket；仅传入该 ticket 即可轮询。作业完成后返回 status: "finished" 和一页结果；仅传入 continuation 可获取下一页；没有 continuation 表示最后一页
• unmappedIds 仅列出 UniProt 报告为失败的标识符。若某行的 UniProtKB 目标处于非活跃状态（已合并、拆分或删除），则会附带 inactive 标记及原因和替代项
• 已完成页面的 continuation 被拒绝（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 会添加直接子分类单元，每页 100 个，并返回总数以及用于获取下一页的 cursor。将游标用于不同分类单元时会报错 invalid_cursor

---

uniprot_get_sequence _工具

• 返回规范序列及其长度和解析后的 FASTA 标头；include_isoforms 会添加异构体序列。登录号来自 uniprot_search_proteins 或 uniprot_map_ids（去掉任何 -N 异构体后缀）
• 已合并的登录号会返回其合并目标的序列，并在 mergedFrom 中注明请求的登录号；已拆分或删除的登录号会报错 not_found，并列出其替代项或 UniParc ID

---

uniprot://entry/{accession} _资源

• 与单个登录号的 uniprot_get_entry 返回相同记录，通过 URI 寻址。非活跃登录号（已合并、拆分或删除）会报错 not_found
• 超大型条目会返回身份摘要（登录号、条目名称、蛋白质名称、基因、物种、长度、审核状态、注释评分、蛋白质存在证据）以及分节大纲；请使用 uniprot_get_entry（sections: [...]）获取特定分节，因为 URI 不接受分节参数

---

uniprot://taxonomy/{taxonId} _资源

• 通过 NCBI 分类 ID 寻址，例如人类对应的 uniprot://taxonomy/9606
• 返回学名、俗名、助记符、等级、父级和完整谱系——结构与不带 include_children 的 uniprot_get_taxonomy 相同
• 仅支持工具的客户端可通过 uniprot_get_taxonomy 获取相同数据

---

uniprot_protein_dossier _提示词

• 参数：必需的 identifier（基因名称、登录号或蛋白质名称）；可选的 organism，用于消除歧义
• 生成的消息中内嵌五步工作流：解析标识符 → 获取条目 → 总结功能／定位／来源 → 获取疾病与变异信息 → 提供结构（PDB）、生物活性（ChEMBL）和引文（PubMed）的交叉引用
• 返回一条包含完整说明的用户角色消息，不附带单独的助手引导消息

功能

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

UniProt 专属功能：

• 无需密钥——UniProt REST 无需 API 密钥；可使用任何兼容 rest.uniprot.org 的基础地址（设置 UNIPROT_BASE_URL 以覆盖为私有镜像）
• 批量获取条目——一次往返获取 N 个登录号，并标记所有未找到的条目
• 异步 ID 映射，支持有界轮询、运行中任务的可恢复票据，以及分页结果

面向 Agent 的输出：

• 来源信息是数据，而非装饰——每条记录都包含 reviewed、annotationScore、proteinExistence 以及每个字段的 PubMed/ECO 证据，便于 Agent 权衡人工注释与预测注释
• 优雅处理部分失败——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 插桩（跨度、指标、完成日志）。	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。