Screaming Frog SEO Spider MCP Server (headless)

Screaming Frog SEO Spider MCP 服务（无头模式）

这是一个适用于 Screaming Frog SEO Spider 的无头 MCP（Model Context Protocol）服务。它可直接驱动 SF 命令行和已保存的抓取数据库，因此即使 Screaming Frog 图形界面已关闭，Claude（或任何兼容 MCP 的客户端）也能运行抓取、导出抓取数据并分析结果：无论是在笔记本电脑、服务器上，还是在定期审计和 CI 管道中。

这是一个社区项目，与 Screaming Frog 无关。从 SEO Spider v24 起，应用中也内置了官方 MCP。两者的工作方式不同，解决的问题也不同。

与官方 Screaming Frog MCP 的区别

Screaming Frog 在 SEO Spider v24 中发布了官方 MCP 服务。它功能丰富：约有 29 个工具，涵盖抓取控制（启动、暂停、恢复、进度）、报告和可选择字段的批量导出、URL 级检查、截图、嵌入导出，以及可选的 Node.js 脚本运行器和 npm、文件系统读写工具。它有两种运行模式：一种是在已打开的应用中运行 Streamable HTTP 服务，另一种是 STDIO 模式，由 MCP 客户端以无头模式启动 Spider。设置说明见 Claude Desktop 和 LM Studio。

如果你想在交互式会话中获得最大功能（可视化、抓取对比、截图、通过脚本对导出内容进行后处理），请使用官方 MCP。它的功能强大得多，而且由供应商维护。

此服务做出了不同的取舍：它是一个小巧且有意限制功能的封装，基于 SF 的 CLI 和已保存的抓取数据库构建，适用于无人监看的运行场景。

设计上严格受限。 只有九个读取和导出工具，没有其他功能。没有脚本运行器，没有 npm install，也没有文件系统写入权限。官方 MCP 提供这三项功能，其文档也指出，启用 Node 运行时“允许在系统上执行任意代码”，因此只应授予完全可信的客户端使用。此外还有 SF_ALLOWED_DOMAINS 允许列表，用于限制 Agent 可以抓取的内容。Agent 按计划无人值守运行时，如此精简的工具集是一项优势。

可在任何地方轻松安装。 这是一个可通过 pip/uv 安装的 Python 软件包，在 macOS、Linux 或 Windows 上的任何 MCP 客户端（Claude Code、Cursor 等）中，只需一行 stdio 配置即可使用。官方 STDIO 模式以 Claude Desktop 扩展（.mcpb）的形式提供；HTTP 模式则需要打开应用并在设置中启动服务。

进程开销低。 只有在工具实际需要时，Screaming Frog 才会运行。无论选择哪种模式，官方服务本身就是在整个会话期间运行的 Spider 应用。

官方工具集中没有的几个工具： aggregate_crawl_data 可在服务端计算计数和分布（官方要回答“有多少个 404”时，需要完整导出或编写 Node 脚本）；delete_crawl 和 storage_summary 可用于清理 SF 的抓取数据库（其 sf_clear_crawl 会清除已暂停的抓取，而非管理已存储的抓取）；read_crawl_data 可对任意导出内容的任意列进行正则表达式过滤；sf_check 则提供预检诊断，可在你浪费一次抓取之前发现许可证问题和 GUI 数据库锁定。

通过聊天使用时的体验。 官方服务是有状态的：你让它按 ID 加载抓取数据后，Spider 会在会话期间将其保存在内存中，后续问题会在一秒内得到回答。代价是整个对话期间会话都占用 SF 数据库，而且导出内容会以内联方式完整返回，除非模型保存文件并编写 Node 脚本进行筛选（这是官方文档建议的做法，以避免超出上下文窗口）。此服务是无状态的：每次导出都会重新启动 SF CLI，因此首次查询抓取数据时耗时更长，但你可以直接提问（“列出我的抓取数据，导出最新的一份”），无需管理 ID 或会话；读取结果只会返回你要求的筛选行，并且数据库会在调用之间释放。对于“显示我这次 10 万 URL 抓取中的 404”这样的请求，两者的区别就在于：返回完整导出内容并占用上下文，还是只返回一页匹配行。

典型的分工方式是：在 GUI 中使用完整配置进行交互式抓取，完成后关闭 GUI，再让此服务处理无人值守的任务。它适用于计划审计、CI 检查，以及让 Agent 查询已保存的数据。两者都要求同一台机器上安装已授权的 Screaming Frog；它们都不是云端爬虫。请注意，此服务要求关闭 GUI（SF 的数据库一次只允许一个进程使用）。

查看实际效果

Pre-Launch Website Audit 是一款用于 Claude Code 的技能，借助此 MCP 服务进行技术 SEO 和页面内审计、全站爬取数据、自定义提取，以及跨所有 URL 的批量分析。该技能会运行 5 项协同子审计，无需 SF 也能工作（使用 bash 后备方案），但对于依赖爬取数据的检查，Screaming Frog 是最大的升级。

前提条件

1. 在机器上安装 Screaming Frog SEO Spider（已使用 v23.x 和 v24.x 测试，应该也适用于 v16+）。 下载地址：https://www.screamingfrog.co.uk/seo-spider/

2. **有效的 Screaming Frog 许可证。**免费版的爬取上限为 500 个 URL。大多数 MCP 功能（无头 CLI、保存/加载爬取、导出）都需要付费许可证。

3. Screaming Frog 中的数据库存储模式（“File > Settings > Storage Mode”；当前安装版本的默认模式）。list_crawls、export_crawl 和其他数据工具会读取 SF 的内部爬取数据库。使用内存存储模式时，crawl_site 仍可正常工作，但每次爬取都会保存为 .seospider 文件（状态输出会告知文件位置），而数据工具无法读取这些文件。

4. Python 3.10+

重要提示：工作流的运行方式

Screaming Frog 使用的内部数据库同一时间只能由一个进程访问。这意味着：

必须先关闭 Screaming Frog GUI，MCP 服务才能访问爬取数据。

典型工作流如下：

1. 运行爬取——可以通过 SF GUI（使用所有自定义设置、筛选条件等）运行，也可以使用 MCP crawl_site 工具。
2. 关闭 Screaming Frog GUI——GUI 会锁定爬取数据库。GUI 运行期间，MCP 服务的无头 CLI 无法读取或导出数据。
3. 使用 MCP 工具——GUI 关闭后，你可以通过 AI 助手列出爬取记录、导出数据、读取 CSV 等。

如果忘记关闭 GUI，服务会检测到这一情况，并显示清晰的错误消息，提示你先退出 SF。

设置

选项 A：从 PyPI 安装（推荐）

将其安装为持久化的 uv 工具，以便服务立即启动：

uv tool install screaming-frog-mcp

这会在 PATH 中添加一个 screaming-frog-mcp 可执行文件（通常位于 ~/.local/bin/screaming-frog-mcp）。之后可使用 uv tool upgrade screaming-frog-mcp 更新。

也可以使用 pip 安装：

pip install screaming-frog-mcp

避免在 MCP 客户端配置中使用 uvx screaming-frog-mcp。uvx 会在启动时解析并下载软件包环境。缓存为空时，这可能会超过客户端 60 秒的初始化超时时间，导致间歇性出现“Could not attach to MCP server”错误。持久化安装在启动时不会访问网络。

选项 B：克隆并从源代码安装

git clone https://github.com/bzsasson/screaming-frog-mcp.git
cd screaming-frog-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

配置 CLI 路径

默认的 Screaming Frog CLI 路径适用于 macOS。如果使用 Linux 或 Windows，请设置 SF_CLI_PATH 环境变量：

操作系统	默认路径
macOS	/Applications/Screaming Frog SEO Spider.app/Contents/MacOS/ScreamingFrogSEOSpiderLauncher
Linux	/usr/bin/screamingfrogseospider
Windows	C:\Program Files (x86)\Screaming Frog SEO Spider\ScreamingFrogSEOSpiderCli.exe

如果你克隆了仓库，请将 .env.example 复制为 .env 并进行编辑。

添加到 Claude Code

如果通过 uv tool install 或 pip 安装：

{
  "mcpServers": {
    "screaming-frog": {
      "command": "/path/to/screaming-frog-mcp",
      "args": [],
      "env": {
        "SF_CLI_PATH": "/path/to/ScreamingFrogSEOSpiderLauncher"
      }
    }
  }
}

使用 which screaming-frog-mcp 查找可执行文件路径（例如，使用 uv tool 安装时，路径为 ~/.local/bin/screaming-frog-mcp）。请使用完整的绝对路径，因为 GUI 应用不会继承 shell 的 PATH。

如果从源代码克隆：

{
  "mcpServers": {
    "screaming-frog": {
      "command": "/path/to/screaming-frog-mcp/.venv/bin/python",
      "args": ["/path/to/screaming-frog-mcp/sf_mcp.py"]
    }
  }
}

添加到 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）中，并使用相同的绝对可执行文件路径：

{
  "mcpServers": {
    "screaming-frog": {
      "command": "/path/to/screaming-frog-mcp",
      "args": [],
      "env": {
        "SF_CLI_PATH": "/path/to/ScreamingFrogSEOSpiderLauncher"
      }
    }
  }
}

编辑配置后，重启 Claude Desktop。

可用工具

工具	说明
sf_check	验证 Screaming Frog 是否已安装，并检查版本和许可证状态
crawl_site	启动无头后台抓取（见下方说明）
crawl_status	检查正在运行的抓取任务进度
list_crawls	列出所有已保存的抓取及其数据库 ID
export_crawl	将抓取数据导出为 CSV 文件（提供多种导出选项）
read_crawl_data	通过分页、筛选和列选择读取已导出的 CSV 数据
aggregate_crawl_data	统计并按组汇总已导出的数据（例如“有多少个 404”“状态码分布”），无需将行数据读入上下文
delete_crawl	从数据库中永久删除抓取记录
storage_summary	显示 SF 抓取存储的磁盘使用情况

使用示例

检查安装情况

“Screaming Frog 已安装并获得许可吗？”

助手会调用 sf_check 并报告版本和许可证信息。

使用已有抓取（推荐流程）

对于大多数用例，建议在 Screaming Frog GUI 中进行抓取，这样你可以完全控制配置、JavaScript 渲染、抓取范围、自定义提取等。然后关闭 GUI，并使用 MCP 分析结果：

在 Screaming Frog GUI 中抓取网站并关闭后：

“列出我保存的抓取” “导出 example.com 的抓取” “显示所有缺少元描述的页面” “哪些页面返回 404？”

通过 MCP 抓取网站（可选）

“抓取 https://example.com”

crawl_site 工具可以通过 CLI 启动无头抓取。这适用于快速重新抓取或自动化工作流，但请注意，与 GUI 相比存在以下限制：

• 使用默认抓取设置（不支持自定义提取、JavaScript 渲染配置等）
• 可以传入 .seospiderconfig 文件来自定义设置（包括抓取 URL 限制），但复杂配置在 GUI 中操作更方便
• 必须等抓取完成并保存后，才能导出数据

导出选项

该服务支持 Screaming Frog 的所有导出选项卡、批量导出和报告。请让助手读取 screaming-frog://export-reference 资源以查看完整列表，或直接指定：

export_tabs: "Internal:All,Response Codes:All,Page Titles:All"
bulk_export: "All Inlinks,All Outlinks"
save_report: "Crawl Overview"

配置

环境变量

变量	说明	默认值
SF_CLI_PATH	Screaming Frog CLI 可执行文件的路径	macOS 默认路径
SF_ALLOWED_DOMAINS	允许抓取的目标域名，以逗号分隔。设置后，crawl_site 只接受与这些域名匹配的 URL。	空（允许所有域名）
SF_CONFIG_DIR	包含 crawl_site 可加载的 .seospiderconfig 文件的目录。	~/.config/sf-mcp/configs/
SF_EXPORT_TTL_SECONDS	导出的 CSV 文件在自动清理前的保留时长。多小时审计时可调大此值。	3600（1 小时）
SF_EXPORT_TIMEOUT_SECONDS	export_crawl 操作完成前的最长等待时间。对于非常大的抓取（100k+ 个 URL）可调大此值。	300（5 分钟）

筛选模式

read_crawl_data 通过 filter_mode 参数支持三种筛选模式：

模式	行为	示例
contains（默认）	不区分大小写的子字符串匹配	filter_value="4" 可匹配 400、204、1450
exact	不区分大小写的精确匹配	filter_value="404" 仅匹配 404
regex	Python 正则表达式（不区分大小写）	filter_value="^[45]" 可匹配 4xx 和 5xx

临时文件清理

导出的 CSV 文件存储在 ~/.cache/sf-mcp/exports/ 中，并会在 1 小时后自动清理（可通过 SF_EXPORT_TTL_SECONDS 配置）。

故障排除

服务完全无法连接？（“Could not attach to MCP server”“failed to connect”）请参阅 TROUBLESHOOTING.md，了解逐步诊断指南：手动测试服务、验证 MCP 握手，以及查找客户端日志。

问题	解决方案
“GUI is already running”错误	退出 Screaming Frog 应用，然后重试
CSV 导出文件为空（仅含标题行，0 条数据）	GUI 可能锁定了数据库，请关闭 GUI 并重新导出
找不到 CLI	检查 .env 中的 SF_CLI_PATH 是否指向正确的可执行文件
list_crawls 中没有显示爬取记录	关闭 GUI 前，确保已在 GUI 中保存爬取记录（File > Save）。如果通过 crawl_site 爬取，请检查 SF 是否处于数据库存储模式：在内存模式下，爬取结果会保存为文件，且 crawl_status 会报告其路径
输出目录中存在 “crawl.seospider” 导致 FATAL 错误	已在 v0.4.2 中修复：每次爬取现在都会使用独立的输出文件夹。请使用 uv tool upgrade screaming-frog-mcp 或 pip install -U screaming-frog-mcp 更新。此错误本身表示 SF 处于内存存储模式；如需完整工作流，请切换到数据库存储模式（'File > Settings > Storage Mode'）
导出超时	大型爬取可能需要更多时间，请将 SF_EXPORT_TIMEOUT_SECONDS 设为更高的值（例如 600），或减少导出标签页的数量
list_crawls 在 Windows 上失败	已在 v0.2.2 中修复，请使用 uv tool upgrade screaming-frog-mcp 或 pip install -U screaming-frog-mcp 更新
“Could not attach to MCP server”／初始化超时	你的配置通过 uvx 启动服务，它会在启动时下载依赖项，在缓存为空时可能超过 60s 握手超时。请改用持久安装方式（uv tool install screaming-frog-mcp），并按照设置中的说明，将 command 指向已安装的可执行文件

许可证

MIT