blastp_mcp

blastp_mcp 将 NCBI BLAST+ 的 blastp 包装为 FastMCP 服务，提供可审计的蛋白质同源性搜索，支持本地产物输出、结构化元数据和数据库状态查询。

设计理念

每次搜索都是可追溯的运行记录。blastp_mcp 不会只返回结果然后丢弃中间产物——它会将查询序列、BLAST 命令参数、标准输出/错误日志、原始 outfmt7 结果、CSV 命中和候选 FASTA 全部写入 runs/<run_id>/ 目录，形成可复查、可重放的运行档案。

Related MCP server: Bio-MCP BLAST

项目结构

blastp_mcp/
├── src/
│   ├── server.py          # FastMCP 服务入口，注册 7 个工具
│   ├── blast_service.py   # 核心搜索逻辑：序列解析、参数校验、blastp 调用
│   ├── blast_process.py   # outfmt7 解析 → CSV + 候选 FASTA
│   ├── db_manager.py      # BLAST 数据库管理：别名解析、状态检查、文件扫描
│   └── job_manager.py     # 异步任务管理：提交、状态、结果、日志、取消
├── tests/                 # 测试文件
├── examples/              # 示例 FASTA 序列
├── fixtures/              # 测试用 outfmt7 样本
├── quick_setup.sh         # 一键环境安装脚本
└── requirements.txt

MCP 工具

工具参数

search_homology_quick：

• sequence（必填）：蛋白质序列，支持 FASTA 格式或纯序列

• evalue：E 值阈值，默认 1e-5

• max_target_seqs：最大返回命中数，默认 20

• include_alignments：是否包含比对详情，默认 false

submit_homology_search：

• sequence（必填）：蛋白质序列

• database：目标数据库，可选 tiered（默认，从 SwissProt 开始分级搜索）、swissprot、refseq、nr

• evalue：E 值阈值，默认 1e-5

• max_target_seqs：最大返回命中数，默认 50

• num_threads：CPU 线程数，默认 4

• include_alignments：是否包含比对详情，默认 false

快速开始

bash quick_setup.sh

安装脚本会自动完成以下步骤：

1. 创建 Python 虚拟环境 ./env/

2. 安装 Python 依赖

3. 检查 blastp、makeblastdb、blastdbcmd、update_blastdb.pl 是否可用；如果缺失，会从 NCBI 官方 BLAST+ LATEST 目录下载当前平台对应的 standalone BLAST+ 包，并安装到本仓库本地 ./tools/

4. 下载并验证 SwissProt 数据库

数据库存储路径由环境变量 BLAST_DB_DIR 指定，未设置时默认使用 ./db/。

BLAST+ 安装路径由 BLAST_TOOLS_DIR 指定，未设置时默认使用 ./tools/。如果运行环境已经安装 BLAST+，可以通过 BLAST_BIN_DIR=/path/to/ncbi-blast/bin 直接指定。若需要关闭自动安装，可设置 BLAST_MCP_AUTO_INSTALL_BLAST=0。高级场景下也可以用 BLAST_PLUS_URL 指定固定版本的 NCBI BLAST+ tar.gz 下载地址。

数据库策略

手动安装大型数据库

将 BLAST 数据库文件放入 BLAST_DB_DIR 目录，使用对应的实际数据库名称：

• refseq 别名 → refseq_protein

• nr 别名 → nr

# 在确认存储空间、网络条件和审批后执行
update_blastdb.pl --decompress refseq_protein
update_blastdb.pl --decompress nr

Tiered 分级搜索

当 database 设为 tiered（默认）时，系统先从 SwissProt 开始搜索：

• 如果命中结果 > 0，直接返回，不再搜索更大的数据库

• 如果没有命中，返回 partial 状态并提示 RefSeq/nr 未下载，建议手动准备后重试

运行产物

每次搜索在 runs/<run_id>/ 下生成完整档案：

runs/<run_id>/
├── query.fasta              # 查询序列（含 SHA256 哈希）
├── blast_command.json       # 完整命令行参数和环境元数据
├── blast_stdout.log         # blastp 标准输出
├── blast_stderr.log         # blastp 标准错误
├── blast_results.outfmt7    # BLAST outfmt 7 格式原始结果
├── blast_hits.csv           # 结构化命中表格
├── candidates/              # 逐条候选序列 FASTA
├── candidates.fasta         # 合并候选序列 FASTA
└── result_summary.json      # 最终结果摘要

BLAST 输出使用 outfmt 7 格式，字段包括 qseqid sseqid pident length mismatch gapopen qstart qend sstart send evalue bitscore stitle sseq。blast_process.py 负责解析并生成 CSV 和候选 FASTA。

环境变量

注册到 Claude Code

claude mcp add blastp_mcp -- /path/to/env/bin/python /path/to/blastp_mcp/src/server.py

或使用 quick_setup.sh 末尾打印的注册命令。

故障排查