foldseek-mcp

独立的 FastMCP 服务端，封装 FoldSeek easy-search 功能。

本项目面向 ProteinMCP/Claude 风格的 MCP 客户端，对 FoldSeek CLI 进行了结构化封装，提供参数校验、边界限制、隔离的作业目录、JSON 摘要、日志、命令元数据以及可复现的执行清单。

MCP 工具

• foldseek_search_structure：使用 PDB/mmCIF 结构文件在已配置的 FoldSeek 数据库中搜索。

• foldseek_search_sequence：使用 ProstT5 模型，以 FASTA 文本或 FASTA 文件在结构数据库中搜索。

• foldseek_list_databases：列出已安装的数据库、可用目录条目、模型状态及 Agent 推荐。

• foldseek_download_database：显式下载目录中列出的某个数据库。

• foldseek_validate_environment：检查 FoldSeek 二进制文件、资源根目录、最小资源及运行目录的可写性。

Related MCP server: ESMfold MCP Server

支持的输入

结构搜索接受 FoldSeek 支持的结构文件，如 .pdb 和 .cif。 序列搜索接受以下之一：

• fasta_text

• fasta_path

路径必须位于配置的允许根目录下。

最小资源

首次运行所需的最小资源：

• pdb100：默认的小型 FoldSeek 数据库。

• prostt5-q4_0-gguf：FASTA 搜索使用的模型。

启用自动下载时，服务端会在搜索前尝试准备缺失的最小资源。大型可选数据库不会被静默下载，而是返回需要确认或手动操作的响应。

推荐的可选数据库：

• afdb_swissprot

• afdb_proteome

• cath50

安装

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

quick_setup.sh 会把 MCP 运行所需的托管文件安装在本仓库内部，不要求用户修改系统 PATH：

• vendor/foldseek/：托管的 FoldSeek 可执行文件或便携兼容后端。

• data/databases/：托管数据库文件与安装元数据。

• data/models/：托管模型文件与安装元数据。

• runs/：搜索作业目录与 artifacts。

Linux/macOS 下，setup 会在没有托管 binary 时下载 FoldSeek 官方 release 到 vendor/foldseek/。Windows 下，官方 release 当前没有原生二进制文件，setup 会在 vendor/foldseek/ 创建便携兼容后端，用于保证 MCP 服务、工具调用、artifact 生成和安装链路无需额外系统安装即可运行。

如需使用系统级 FoldSeek，也可以单独安装，例如：

conda install -c conda-forge -c bioconda foldseek

Windows 用户可以使用 Conda/Mamba，或通过 FOLDSEEK_MCP_FOLDSEEK_BINARY 指定可执行文件路径。

运行

foldseek-mcp

开发模式：

fastmcp dev src/foldseek_mcp/server.py

配置

复制 .env.example 并调整路径：

• FOLDSEEK_MCP_DATABASE_ROOT

• FOLDSEEK_MCP_MODEL_ROOT

• FOLDSEEK_MCP_RUN_ROOT

• FOLDSEEK_MCP_FOLDSEEK_BINARY

• FOLDSEEK_MCP_AUTO_DOWNLOAD

• FOLDSEEK_MCP_MAX_AUTO_DOWNLOAD_GB

• FOLDSEEK_MCP_ALLOWED_INPUT_ROOTS

数据库和 FoldSeek 的默认配置位于：

• configs/databases.example.yaml

• configs/foldseek.example.yaml

产物

每次搜索会在 runs/jobs/<job_id>/ 下生成：

• 标准化后的查询文件

• results.tsv

• results.json

• stdout.log

• stderr.log

• command.json

• manifest.json

• 可选的 results.html

manifest.json 记录了查询类型、输入哈希、数据库/模型路径、FoldSeek 版本、命令参数、时间戳、状态、退出码以及产物路径。

常见问题

• foldseek_not_found：安装 FoldSeek 或设置 FOLDSEEK_MCP_FOLDSEEK_BINARY。

• database_missing：调用 foldseek_download_database 或手动将数据库放到配置的根目录下。

• prostt5_model_missing：启用自动下载或将模型放到配置的模型根目录下。

• auto_download_limit_exceeded：增大 FOLDSEEK_MCP_MAX_AUTO_DOWNLOAD_GB 或显式确认大型下载。

• invalid_input：确保路径在允许的根目录下，且 FASTA 包含合法的蛋白质残基字符。