Screaming Frog SEO Spider MCP Server (headless)

Screaming Frog SEO Spider MCP Server（ヘッドレス）

Screaming Frog SEO Spider 用のヘッドレス MCP（Model Context Protocol）サーバーです。SF のコマンドラインと保存済みのクロールデータベースを直接操作するため、Claude（または MCP 互換のクライアント）で、Screaming Frog の GUI を閉じたままクロールの実行、クロールデータのエクスポート、結果の分析ができます。ノート PC、サーバー、またはスケジュールされた監査や CI パイプライン内で利用できます。

これはコミュニティプロジェクトであり、Screaming Frog とは提携していません。SEO Spider v24 以降では、アプリに組み込まれた公式 MCP も利用できます。この 2 つは動作の仕組みが異なり、それぞれ異なる課題を解決します。

公式の Screaming Frog MCP との違い

Screaming Frog は SEO Spider v24 で公式 MCP サーバーをリリースしました。機能は充実しており、クロール制御（開始、一時停止、再開、進行状況）、フィールド選択が可能なレポートと一括エクスポート、URL 単位の検査、スクリーンショット、埋め込みデータのエクスポートのほか、オプションで npm とファイルシステムの読み書きツールを備えた Node.js スクリプトランナーを含む、約 29 個のツールを提供します。実行モードは 2 種類あります。起動中のアプリ内で動作する Streamable HTTP サーバーと、MCP クライアントが Spider 自体をヘッドレスで起動する STDIO モードです。Claude Desktop と LM Studio の設定方法がドキュメントに記載されています。

対話セッションで最大限の機能（可視化、クロール比較、スクリーンショット、エクスポートのスクリプトによる後処理）が必要なら、公式 MCP をお使いください。できることがはるかに多く、ベンダー自身がメンテナンスしています。

このサーバーは別の選択をしています。SF の CLI と保存済みクロールデータベースを対象とした、小規模で意図的に機能を絞ったラッパーで、誰も監視していない状態での実行向けに作られています。

設計段階から制限を徹底しています。 読み取りとエクスポートを行う 9 つのツールのみで、それ以外はありません。スクリプトランナーも、npm install も、ファイルシステムへの書き込みアクセスもありません。公式 MCP はこの 3 つをすべて提供しており、公式ドキュメントにも、Node ランタイムを有効にすると「システム上で任意のコードを実行できる」ため、完全に信頼できるクライアントにのみ許可すべきだと記載されています。また、エージェントがクロールできる対象を制限する SF_ALLOWED_DOMAINS 許可リストもあります。エージェントをスケジュールに沿って無人で実行する場合、ツールの範囲がこれほど小さいことは利点です。

どこにでも簡単にインストールできます。 macOS、Linux、Windows 上の任意の MCP クライアント（Claude Code、Cursor など）で使える、pip/uv からインストール可能な Python パッケージで、stdio 設定も 1 行です。公式の 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 がセッション中メモリに保持し、続く質問には 1 秒もかからず回答します。その代わり、会話中は SF のデータベースがセッションに占有されます。また、モデルがファイルを保存し、Node スクリプトを書いてデータを抽出しない限り、エクスポートはインラインの全データとして返されます（コンテキストウィンドウ内に収めるために、公式ドキュメントでも推奨されている方法です）。このサーバーはステートレスです。エクスポートのたびに SF CLI を新たに起動するため、クロールに対する最初の回答には時間がかかりますが、ID やセッションを管理せずに「クロールを一覧表示して、最新のものをエクスポートして」と頼むだけで済みます。読み取り結果には、要求した条件に一致する行だけが返され、呼び出しの間はデータベースが解放されます。「10 万 URL のクロールから 404 を表示して」という場合、違いは、全エクスポートをコンテキストに含めるか、一致した行だけを 1 ページ分表示するかです。

一般的な使い分けとしては、GUI で設定をすべて反映して対話的にクロールし、GUI を閉じてから、このサーバーで無人処理を行います。これにより、スケジュールされた監査、CI チェック、保存済みデータを照会するエージェントに対応できます。どちらも同じマシンにライセンス済みの Screaming Frog がインストールされている必要があり、どちらもクラウドクローラーではありません。このサーバーの使用中は GUI を閉じる必要があります（SF のデータベースは一度に 1 つのプロセスしか許可しません）。

動作例

Claude Code 向けの Pre-Launch Website Audit スキルは、この 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 ライセンス。 無料版ではクロールできる URL 数が 500 件に制限されます。多くの MCP 機能（ヘッドレス CLI、クロールの保存／読み込み、エクスポート）には有料ライセンスが必要です。

3. Screaming Frog の Database storage mode（「File > Settings > Storage Mode」。現在のインストールではデフォルトの設定です）。list_crawls、export_crawl、その他のデータツールは、SF の内部クロールデータベースを読み取ります。メモリストレージモードでも crawl_site は動作しますが、各クロールは .seospider ファイルとして保存され（保存場所はステータス出力に表示されます）、データツールからは参照できません。

4. Python 3.10+

重要：ワークフローの仕組み

Screaming Frog は内部データベースを使用しており、一度にアクセスできるプロセスは 1 つだけです。つまり、次の点に注意してください。

MCP サーバーがクロールデータにアクセスする前に、Screaming Frog の GUI を閉じる必要があります。

通常のワークフローは次のとおりです。

1. クロールを実行する — SF の GUI（カスタム設定やフィルターなどをすべて適用）または MCP の crawl_site ツールを使用します。
2. Screaming Frog の GUI を閉じる — GUI がクロールデータベースをロックします。GUI の実行中は、MCP サーバーのヘッドレス CLI でデータを読み取ったりエクスポートしたりできません。
3. MCP ツールを使用する — GUI を閉じると、AI アシスタントからクロールの一覧表示、データのエクスポート、CSV の読み取りなどを実行できます。

GUI を閉じ忘れた場合、サーバーがそれを検出し、最初に SF を終了するよう明確なエラーメッセージを表示します。

セットアップ

オプション A：PyPI からインストール（推奨）

永続的な uv tool としてインストールすると、サーバーがすぐに起動します。

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 環境変数を設定してください。

OS	デフォルトパス
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 アプリはシェルの 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 を呼び出し、バージョンとライセンスの情報を報告します。

既存のクロールを操作する（推奨フロー）

ほとんどの用途では、設定、JavaScript のレンダリング、クロール範囲、カスタム抽出などを完全に制御できる Screaming Frog GUI でクロールしてください。その後、GUI を閉じて MCP を使い、結果を分析します。

Screaming Frog GUI でサイトをクロールし、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 操作の完了を待つ最大時間です。非常に大規模なクロール（URL 数 100k 以上）では値を増やしてください。	300（5 分）

フィルターモード

read_crawl_data は、filter_mode パラメーターを使って 3 つのフィルターモードに対応しています。

モード	動作	例
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 で閉じる前にクロールを保存（File > Save）したことを確認してください。crawl_site でクロールした場合は、SF がデータベースストレージモードになっていることを確認してください。メモリモードではクロールはファイルとして保存され、crawl_status にそのパスが表示されます
出力ディレクトリに「crawl.seospider exists in output directory」という致命的エラーが表示される	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）を設定するか、エクスポートするタブを減らしてください
Windows で list_crawls が失敗する	v0.2.2 で修正済みです。uv tool upgrade screaming-frog-mcp または pip install -U screaming-frog-mcp でアップデートしてください
「Could not attach to MCP server」／初期化がタイムアウトする	設定で uvx 経由でサーバーを起動しています。起動時に依存関係をダウンロードするため、キャッシュが空の場合は 60 秒のハンドシェイクタイムアウトを超えることがあります。セットアップ に従って、永続的なインストール（uv tool install screaming-frog-mcp）に切り替え、インストール済みの実行ファイルを command に指定してください

ライセンス

MIT