foldseek-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@foldseek-mcp search PDB 1abc against pdb100"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
foldseek-mcp
独立的 FastMCP 服务端,用 MCP 工具封装 FoldSeek easy-search。
本项目面向 ProteinMCP / Claude / Agent Runtime 使用。MCP 负责参数校验、路径安全、Docker/FoldSeek 调用、结果解析、日志、artifact、command.json 和 manifest.json 记录。
MCP Tools
foldseek_search_structure:用 PDB/mmCIF 结构文件搜索官方 FoldSeek 数据库。foldseek_search_sequence:用 FASTA 文本或 FASTA 文件搜索结构数据库。foldseek_list_databases:列出已安装数据库、可用官方数据库、模型状态和 Agent 建议。foldseek_download_database:显式下载官方 FoldSeek 数据库。foldseek_validate_environment:检查 Docker/FoldSeek、数据库目录、模型目录和运行目录。
Related MCP server: ESMfold MCP Server
默认数据库策略
默认官方数据库 alias:
afdb_uniprot50_minimal对应 FoldSeek 官方数据库名:
Alphafold/UniProt50-minimal注意:该官方库约 114GB,不会在普通安装时静默下载。需要显式确认后下载,或由外部流程提前下载好并挂载/配置给 MCP。
不再把自建 fixture 数据库作为默认科学搜索数据库。fixture 只能用于链路 smoke test,不能替代官方数据库。
推荐部署方式
大型 FoldSeek 数据库不要打进 MCP Docker 镜像。推荐:
MCP 镜像只包含运行环境、FoldSeek runtime、MCP 代码。
官方数据库放在服务器持久化目录。
运行时通过 volume 或环境变量挂载。
示例目录:
/opt/mgi/foldseek-mcp/
/data/foldseek/databases/afdb_uniprot50_minimal/
/data/foldseek/models/
/data/foldseek/runs/如果你先在 Windows 下载到 E:\download\foldseek,服务器上可以拷贝成:
/data/foldseek/databases/afdb_uniprot50_minimal/然后设置:
FOLDSEEK_MCP_DATABASE_ROOT=/data/foldseek/databases
FOLDSEEK_MCP_MODEL_ROOT=/data/foldseek/models
FOLDSEEK_MCP_RUN_ROOT=/data/foldseek/runs
FOLDSEEK_MCP_BACKEND=docker
FOLDSEEK_MCP_DOCKER_IMAGE=openeuler/foldseek:10-941cd33-oe2403sp3
FOLDSEEK_MCP_AUTO_DOWNLOAD=false数据库 prefix 应为:
<DATABASE_ROOT>/afdb_uniprot50_minimal/afdb_uniprot50_minimal下载官方数据库
通过 MCP 工具下载时,需要显式确认大体积下载:
{
"database": "afdb_uniprot50_minimal",
"confirm_large": true
}也可以直接用 Docker 下载到外部目录:
$ROOT = "E:\download\foldseek"
New-Item -ItemType Directory -Force -Path "$ROOT\databases\afdb_uniprot50_minimal\tmp"
docker pull openeuler/foldseek:10-941cd33-oe2403sp3
docker run --rm `
-v "${ROOT}:/data" `
openeuler/foldseek:10-941cd33-oe2403sp3 `
foldseek databases "Alphafold/UniProt50-minimal" `
/data/databases/afdb_uniprot50_minimal/afdb_uniprot50_minimal `
/data/databases/afdb_uniprot50_minimal/tmp `
--threads 8安装
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"或:
bash quick_setup.shWindows 默认使用 Docker 后端。如果 Docker Desktop 未启动,MCP 会返回结构化错误 docker_unavailable,提示用户启动 Docker。
运行
python -m foldseek_mcp.serverLocal-first remote fallback
Search tools use local-first, remote-fallback:
If the requested database is installed or mounted locally, MCP runs local
foldseek easy-search.If the local database is missing and
FOLDSEEK_MCP_REMOTE_FALLBACK=true, MCP calls the official Foldseek Web API.If the remote API also fails, MCP returns a structured error with a local database remediation hint.
Remote fallback configuration:
FOLDSEEK_MCP_REMOTE_FALLBACK=true
FOLDSEEK_MCP_REMOTE_BASE_URL=https://search.foldseek.com
FOLDSEEK_MCP_REMOTE_TIMEOUT_SECONDS=900
FOLDSEEK_MCP_REMOTE_POLL_INTERVAL_SECONDS=2.0Remote alias mapping:
afdb_uniprot50_minimal -> afdb50
afdb_swissprot -> afdb-swissprot
afdb_proteome -> afdb-proteome
pdb -> pdb100
cath50 -> cath50search.foldseek.com is suitable as a free fallback path, but it is a public web server API rather than a production SLA service. For reproducibility, compliance, or private structures, mount local databases and set:
FOLDSEEK_MCP_REMOTE_FALLBACK=falseArtifacts
每次搜索会创建:
runs/jobs/<job_id>/
query.pdb 或 query.fasta
results.tsv
results.json
stdout.log
stderr.log
command.json
manifest.jsonmanifest.json 记录 query hash、数据库 alias、数据库 path/prefix、FoldSeek 版本、命令参数、时间戳、状态和 artifact 路径。
常见错误
docker_unavailable:Windows Docker 后端不可用,启动 Docker Desktop 后重试。docker_image_missing:本地没有 FoldSeek Docker 镜像,运行quick_setup.sh或docker pull openeuler/foldseek:10-941cd33-oe2403sp3。auto_download_limit_exceeded:官方库体积超过自动下载阈值,需要显式confirm_large=true。database_missing:官方数据库未下载或未挂载到FOLDSEEK_MCP_DATABASE_ROOT。foldseek_nonzero_exit:FoldSeek 命令执行失败,查看该 job 的stderr.log和command.json。
Available Tools
5 toolsfoldseek_download_databaseC
Download or prepare a catalog-listed FoldSeek database.
Inputs: database (required), confirm_large. Returns: object
foldseek_list_databasesA
List installed and available FoldSeek databases and model resources.
Inputs: no named parameters. Returns: object
foldseek_search_sequenceC
Run FoldSeek easy-search with a FASTA query and configured ProstT5 model.
Inputs: model, evalue, threads, use_gpu, +8 more. Returns: object
foldseek_search_structureC
Run FoldSeek easy-search with a PDB/mmCIF structure query.
Inputs: query_path (required), evalue, threads, use_gpu, +6 more. Returns: object
foldseek_validate_environmentA
Validate the local FoldSeek MCP runtime environment.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct operation: database download, listing, sequence search, structure search, and environment validation. No functional overlap.
All tools follow the consistent pattern 'foldseek_verb_noun' with clear, descriptive names (e.g., foldseek_download_database, foldseek_search_sequence).
Five tools is appropriate for a focused scientific server covering database management, two search modalities, and environment checks.
Core workflows are covered, but missing a tool to delete or update databases, which is a minor gap for full lifecycle management.
Related MCP Connectors
Fold proteins, co-fold ligands with binding affinity, design binders and embed sequences.
Federated protein structure & annotation across experimental (PDB) and predicted (AlphaFold) models.
Run protein folding, docking, design and sequence analysis tools, and read their results.
Protein analysis: ESM-2/ESMC embeddings, mutation scoring, landscape scans, ESMFold structure.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables searching, retrieving, and downloading protein structure data from the RCSB Protein Data Bank. Supports intelligent protein structure search, comprehensive data retrieval, and multiple file format downloads for bioinformatics research.322 PyPIMIT
- FlicenseNot gradedqualityDmaintenanceEnables protein sequence analysis and structure prediction by extracting ESM-2 embeddings and batch processing FASTA files via Docker. It provides tools for large-scale embedding extraction, job monitoring, and model management within an MCP-compatible environment.-
- FlicenseBqualityDmaintenanceProvides programmatic access to AlphaFold protein structure predictions and UniProt data, enabling users to retrieve protein structures, summaries, and annotations through natural language.3-
- FlicenseNot gradedqualityCmaintenanceEnables AI-powered protein structure prediction and variant analysis via Docker, with tools for submitting predictions, batch processing variants, and monitoring jobs.2-