UniProt MCP Server

UniProt MCP 服务

一个用于访问 UniProt 蛋白质信息的模型上下文协议（MCP）服务。此服务允许 AI 助手直接从 UniProt 获取蛋白质功能和序列信息。

功能

• 尚不清楚登录号时，按蛋白质名称、基因名称或关键字搜索 UniProtKB
• 按 UniProt 登录号获取蛋白质信息
• 批量检索多个蛋白质
• 获取带有位置标注的序列特征：信号肽、前肽、成熟链、活性位点和结合位点、二硫键、结构域、糖基化、天然变体和诱变信息
• 获取可用结构：包含方法、分辨率和覆盖残基范围的 PDB 条目，以及 AlphaFold DB 模型
• 缓存可提升性能（TTL 为 24 小时），读取同一条目的工具共享缓存
• 错误处理和日志记录

要求

• Python 3.10 或更高版本
• MCP Python SDK 1.x（mcp>=1.1,<2）

MCP SDK 2.0 版本从本项目所基于的低级别 Server 类中移除了 @server.list_tools() / @server.call_tool() 装饰器。若安装的是 mcp 2.x，服务启动时会引发 AttributeError: 'Server' object has no attribute 'list_tools'，因此依赖项固定在 1.x 系列。迁移到 2.x 服务 API 的工作另行跟踪。

快速开始

1. 确保已安装 Python 3.10 或更高版本
2. 克隆此代码库：

   git clone https://github.com/TakumiY235/uniprot-mcp-server.git
   cd uniprot-mcp-server
   

3. 安装依赖项：

   # Using uv (recommended)
   uv pip install -r requirements.txt
   
   # Or using pip
   pip install -r requirements.txt
   

配置

将以下内容添加到 Claude Desktop 配置文件：

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

{
  "mcpServers": {
    "uniprot": {
      "command": "uv",
      "args": ["--directory", "path/to/uniprot-mcp-server", "run", "uniprot-mcp-server"]
    }
  }
}

使用示例

在 Claude Desktop 中配置服务后，你可以提出如下问题：

Can you get the protein information for UniProt accession number P98160?

批量查询：

Can you get and compare the protein information for both P04637 and P02747?

手头没有登录号时：

Find the reviewed human phospholipase A2 entries and show me their lengths.

在设计构建体或变体面板之前，获取必须遵循的边界和残基信息：

What are the signal peptide, propeptide and mature chain boundaries of P04054,
and where are its active sites and disulfide bonds?

查找可供研究的结构：

Which PDB structures cover P04054, and at what resolution?

API 参考

工具

1. get_protein_info

   • 获取单个蛋白质的信息
   • 必需参数：accession（UniProt 登录号）
   • 响应示例：

     {
       "accession": "P12345",
       "protein_name": "Example protein",
       "function": ["Description of protein function"],
       "sequence": "MLTVX...",
       "length": 123,
       "organism": "Homo sapiens"
     }
     

2. get_batch_protein_info

   • 获取多个蛋白质的信息
   • 必需参数：accessions（UniProt 登录号数组）
   • 返回蛋白质信息对象数组
   • 每个登录号都会单独报告查询失败的情况，因此某个条目出错不会导致批次中的其他结果丢失

3. search_proteins

   • 在尚不清楚登录号时查找条目
   • 必需参数：query（搜索词；支持 UniProt 查询语法，例如 gene:PLA2G1B）
   • 可选参数：organism_id（NCBI 分类 ID，例如人类为 9606）、reviewed_only（默认值为 true，仅限 Swiss-Prot）、limit（1-50，默认值为 10）
   • 不包含序列，因此结果列表较小
   • 响应示例：

     {
       "count": 1,
       "results": [
         {
           "accession": "P04054",
           "entry_name": "PA2GA_HUMAN",
           "protein_name": "Phospholipase A2",
           "gene_names": ["PLA2G1B"],
           "organism": "Homo sapiens",
           "taxon_id": 9606,
           "length": 148,
           "reviewed": true
         }
       ]
     }
     

4. get_protein_features

   • 获取带注释的序列特征，位置采用从 1 开始的闭区间
   • 必需参数：accession
   • 可选参数：types（仅保留这些特征类型，匹配时不区分大小写，例如 ["Active site", "Disulfide bond"]）、include_secondary_structure（默认值为 false）
   • 二级结构（Helix、Beta strand、Turn）按元素报告，因此一个条目会包含数十个这类结构，而它们对序列设计决策毫无帮助。除非设置 include_secondary_structure，或在 types 中指定这些结构，否则不会返回它们。
   • 响应示例：

     {
       "accession": "P04054",
       "length": 148,
       "feature_counts": {"Signal": 1, "Propeptide": 1, "Chain": 1,
                          "Active site": 2, "Disulfide bond": 7},
       "features": [
         {"type": "Signal", "start": 1, "end": 15, "description": ""},
         {"type": "Propeptide", "start": 16, "end": 22,
          "description": "Activation peptide"},
         {"type": "Chain", "start": 23, "end": 148,
          "description": "Phospholipase A2"}
       ]
     }
     

   • 特征按位置排序。对于 UniProt 未标注位置的特征，位置报告为 null，并排在最后。

5. get_protein_structures

   • 获取某种蛋白质的可用结构
   • 必需参数：accession
   • 响应示例：

     {
       "accession": "P04054",
       "pdb_entries": [
         {"pdb_id": "3ELO", "method": "X-ray", "resolution": "1.55 A",
          "chains": "A=16-148"},
         {"pdb_id": "6Q42", "method": "X-ray", "resolution": "1.90 A",
          "chains": "A/B=23-148"}
       ],
       "alphafold_id": "P04054"
     }
     

   • 对于没有已解析结构的蛋白质，会返回空列表和 null 的 alphafold_id，而不是报错

get_protein_info、get_protein_features 和 get_protein_structures 会读取同一 UniProt 条目的不同部分，因此它们会按登录号共享一次缓存请求：查询全部三项只需一次往返。

开发

配置开发环境

1. 克隆仓库
2. 创建虚拟环境：

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. 安装开发依赖：

   pip install -e ".[dev]"
   

运行测试

pytest

代码风格

本项目使用：

• Black 进行代码格式化
• isort 对导入进行排序
• flake8 进行代码检查
• mypy 进行类型检查
• bandit 进行安全检查
• pip-audit 检查依赖项漏洞

运行所有检查：

black .
isort .
flake8 .
mypy .
bandit -r src/
pip-audit .

技术细节

• 使用 MCP Python SDK 构建
• 使用 httpx 发送异步 HTTP 请求
• 使用基于 OrderedDict 的缓存实现缓存，TTL 为 24 小时
• 对每个 UniProt 请求设置超时（连接超时 10 秒，总超时 30 秒）
• 将 UniProt API 错误（包括 429 速率限制）作为工具错误返回；不会自动重试或退避
• 提供详细的错误消息

错误处理

服务端会处理各种错误场景：

• 无效的登录号（UniProt 会返回 400，而不是 404）
• API 连接问题（网络错误）
• 速率限制（429 响应）——将错误报告给调用方，不会重试
• 响应格式错误（JSON 解析错误）
• 缓存管理（TTL 和大小限制）

参与贡献

欢迎贡献！请随时提交 Pull Request。参与贡献的步骤如下：

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 将分支推送到远程仓库（git push origin feature/amazing-feature）
5. 创建 Pull Request

请确保根据需要更新测试，并遵循现有的代码风格。

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

致谢

• 感谢 UniProt 提供蛋白质数据 API
• 感谢 Anthropic 提供 Model Context Protocol 规范
• 感谢帮助改进本项目的贡献者