Uniprot Mcp

uniprot-mcp

GitHub 仓库：fzlzjerry/uniprot-mcp · PyPI 包和命令：uniprotkb-mcp （Python 导入包为 uniprot_mcp）。

一个生产级 MCP 服务，通过 stdio 向大模型客户端（Claude Code、Claude Desktop 等）开放 UniProt REST API。基于 FastMCP 构建，并使用 uv 管理。

工具默认返回精简且节省 token 的摘要，仅在请求时返回完整负载；同时具备可靠的错误处理，并内置 UniProt 查询速查表，帮助模型编写有效查询。

快速开始

已发布到 PyPI——无需克隆或安装：

uvx uniprotkb-mcp

然后将 MCP 客户端指向它（完整配置见下文）：

{
  "mcpServers": {
    "uniprot": {
      "command": "uvx",
      "args": ["uniprotkb-mcp"],
      "env": { "UNIPROT_MCP_CONTACT": "[email protected]" }
    }
  }
}

工具

工具	功能
search_uniprotkb	使用原生查询语法搜索 UniProtKB。自动添加 reviewed / organism_id 筛选条件。支持摘要、FASTA 或 TSV 输出。
get_entry	获取单个条目的精选摘要（功能、名称、物种、长度、亚细胞定位、家族/结构域、关键特征、PTM、关键词、PDB/AlphaFold/Ensembl/RefSeq/InterPro/GO 交叉引用），或获取 json/fasta/txt/gff 格式。
get_fasta	获取单个登录号或批量登录号对应的原始 FASTA。
map_ids	通过 UniProt 的异步 ID 映射跨数据库转换 ID（例如，RefSeq_Protein→UniProtKB、UniProtKB_AC-ID→PDB）。返回映射成功的 ID 对以及未映射的 ID；并根据实时配置验证数据库组合。
get_taxonomy	根据物种名称或分类单元 ID 查询分类单元 ID、名称、等级和谱系。将“human”转换为 organism_id:9606。
search_uniref	搜索 UniRef100/90/50 序列相似性簇。
search_proteomes	搜索蛋白质组（整个物种的蛋白质集合）；支持参考蛋白质组筛选。

此外还提供一个 MCP 资源 resource://uniprot/query-cheatsheet，用于说明 UniProtKB 查询语法（gene:、organism_id:、reviewed:true、length:[X TO Y]、keyword:、ec:、布尔运算符 AND/OR/NOT 等）。

要求

• Python ≥ 3.10（仓库通过 .python-version 固定为 3.13）
• uv

安装

git clone https://github.com/fzlzjerry/uniprot-mcp
cd uniprot-mcp
uv sync                 # creates .venv and installs fastmcp + httpx

运行

# stdio server (what MCP clients launch):
uv run uniprotkb-mcp

UniProt 要求 API 客户端使用联系地址标识自身。通过 UNIPROT_MCP_CONTACT 环境变量设置联系地址（该地址会写入 User-Agent）；否则会使用占位值。

UNIPROT_MCP_CONTACT="[email protected]" uv run uniprotkb-mcp

使用 uvx 运行（无需克隆或同步）

uvx（又称 uv tool run）会在临时环境中获取、构建并运行控制台脚本——无需预先安装。选择你所用的来源：

# From PyPI (published):
uvx uniprotkb-mcp

# From a Git repo (note: repo is uniprot-mcp, command is uniprotkb-mcp):
uvx --from git+https://github.com/fzlzjerry/uniprot-mcp uniprotkb-mcp

# From a local checkout (this directory):
uvx --from /ABSOLUTE/PATH/TO/uniprot-mcp uniprotkb-mcp

# From a built wheel:
uvx --from ./dist/uniprotkb_mcp-0.1.0-py3-none-any.whl uniprotkb-mcp

使用 uvx [email protected] 固定版本，或使用 uvx --refresh --from <source> uniprotkb-mcp 强制刷新缓存的构建。

在 Claude Desktop 中注册

编辑 claude_desktop_config.json （macOS：~/Library/Application Support/Claude/claude_desktop_config.json， Windows：%APPDATA%\Claude\claude_desktop_config.json）并添加：

{
  "mcpServers": {
    "uniprot": {
      "command": "uvx",
      "args": ["uniprotkb-mcp"],
      "env": { "UNIPROT_MCP_CONTACT": "[email protected]" }
    }
  }
}

这会直接从 PyPI 运行已发布的软件包。若要运行尚未发布的代码， 则添加源："args": ["--from", "git+https://github.com/fzlzjerry/uniprot-mcp", "uniprotkb-mcp"] （git）或 "args": ["--from", "/ABSOLUTE/PATH/TO/uniprot-mcp", "uniprotkb-mcp"] （本地检出）。确保 Claude Desktop 能在 PATH 中找到 uvx（它随 uv 一同提供；如有需要，请提供 uvx 的绝对路径，例如 ~/.local/bin/uvx）。 重启 Claude Desktop 后，uniprot 工具就会出现。

更喜欢使用克隆的检出版本，而不是 uvx？请使用 "command": "uv", "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/uniprot-mcp", "uniprotkb-mcp"]。

在 Claude Code 中注册

通过项目根目录下的 .mcp.json 按项目范围注册（格式相同）：

{
  "mcpServers": {
    "uniprot": {
      "command": "uvx",
      "args": ["uniprotkb-mcp"],
      "env": { "UNIPROT_MCP_CONTACT": "[email protected]" }
    }
  }
}

或通过命令行注册：

# via uvx (published / git / local source):
claude mcp add uniprot -e [email protected] -- uvx uniprotkb-mcp

# via a local checkout with uv:
claude mcp add uniprot -e [email protected] \
  -- uv run --directory /ABSOLUTE/PATH/TO/uniprot-mcp uniprotkb-mcp

冒烟测试

针对在线 API 测试每个工具并打印输出：

UNIPROT_MCP_CONTACT="[email protected]" uv run python -m tests.smoke

开发

开发、测试、CI 和发布流程（由 CI 驱动的 PyPI Trusted Publishing——无需令牌）记录在 CONTRIBUTING.md 中。 简而言之：运行 uv sync，然后运行 uv run python -m tests.check_structure（离线）和 uv run python -m tests.smoke（在线 API）。

设计说明

• 单个共享的 httpx.AsyncClient，并设置包含联系信息的描述性 User-Agent。
• 遇到 429（遵循 Retry-After）和 5xx 时进行重试/退避；400 会显示 UniProt 自身的错误消息；不会向客户端传递原始回溯（错误会作为 ToolError 引发）。
• 通过 Link 标头 / x-total-results 进行分页；结果数量上限为 ≤ 500，并始终报告总数，以便你缩小范围或翻页。
• ID 映射遵循实际的异步流程：POST /idmapping/run → 轮询 /idmapping/status/{job}（303 + Location 表示已完成）→ 获取结果，并根据目标数据库自动选择丰富的 UniProtKB 结果端点或简单配对端点。

项目结构

src/uniprot_mcp/
  server.py       # FastMCP instance, the 7 tools, cheat-sheet resource, main()
  client.py       # shared AsyncClient, retry/backoff, error mapping, header parsing
  idmapping.py    # async run/poll/results flow with target-aware routing
  config.py       # cached idmapping db config + from/to validation
  formatting.py   # JSON -> compact summary digests
  cheatsheet.py   # UniProt query cheat-sheet
tests/smoke.py    # live-API smoke test