webshot-mcp

エージェントに目を与える—ブラウザやネットワークは不要。 二つのツール、screenshot と page_text を備えたMCPサーバーで、既に実行中のChrome（CDP経由）に接続し、ページ全体または単一の要素をキャプチャします。ブラウザを起動したりダウンロードしたりすることは一切ありません。プライベートネットワークのターゲットは、SSRF対策されたURLポリシーによってブロックされます。

なぜこれが存在するか

ビジュアルチェック→修正ループをコーディングエージェントで実行した際の二つの教訓から生まれました：

1. スクリーンショットごとにブラウザを起動するのは遅くて不安定な方法です。 持続的なヘッドレスChromium（Dockerサイドカー、CIサービス、--remote-debugging-port 付きのデスクトップChrome）は、ウォームで共有され、信頼性があります。欠けていたのは、規律あるクライアントです：CDP経由で接続し、ショットごとに新しいコンテキストを開き、自分が開いたものだけを閉じ、共有ブラウザを決して殺さないこと。その規律がこのリポジトリです。

2. ネットワーク内のスクリーンショットツールは、カメラ付きのSSRFプロキシです。 「http://169.254.169.254/…」や http://redis.internal:6379/ をスクリーンショットするよう誘導できるエージェントは、喜んでクラウドメタデータエンドポイントを撮影します。そのためURLポリシーは、ループバック、RFC-1918、リンクローカル、CGNAT、v6ローカルターゲットをブロックします—それらに解決されるホスト名も含めて。ただし、ホスト名を明示的に許可リストに追加した場合は除きます。ローカル開発サーバーは正当な例外であり、一つ一つ名前を指定します。

クイックスタート

npm install
npm test        # URL-policy test suite — no browser needed
npm run demo    # policy walkthrough + a real screenshot if a CDP Chrome is reachable

CDP対応Chromeを取得します（以下のいずれか）：

# your installed Chrome, headless
chrome --headless --remote-debugging-port=9222 --remote-debugging-address=127.0.0.1 about:blank

# or a Docker sidecar you keep running
docker run -d -p 127.0.0.1:9222:9222 chromedp/headless-shell

Claude Codeに接続します：

claude mcp add webshot \
  -e WEBSHOT_CDP_URL=http://127.0.0.1:9222 \
  -e WEBSHOT_ALLOW_HOSTS=localhost,127.0.0.1 \
  -- npx tsx src/server.ts

その後、エージェントに「localhost:5177のヒーローセクションをスクリーンショットして— .hero だけで—何がおかしいか教えて」のように依頼します：selector は一つの要素に切り取るため、エージェントの注意（とトークン）を4000ピクセルのページ全体ではなく、議論中の部分に集中させます。

ツール

設計ノート

• ショットごとに新しいコンテキスト、ブラウザは生涯共有。 コンテキストは安価で分離されています（クッキー、キャッシュ、ビューポート）；ブラウザは高価で共有されます。CDP接続での browser.close() は、リモートブラウザを殺さずに切断します—サーバーはChromeに触れずに何度でも再起動できます。

• DNSはチェックされ、リバインディングは文書化されています。 非IPホスト名は解決され、返されたすべてのアドレスはプライベート範囲に対して再検証されます。ブラウザ自身の二回目の解決（古典的なリバインディング）で異なる応答をする悪意のあるDNSサーバーは、スクリーンショットツールの範囲外です—ここで言及されており、曖昧にごまかされていません。

• deviceScaleFactor: 2 — レティナキャプチャ。エージェント（と人間）は、スクリーンショットのぼやけたテキストを思ったより頻繁に誤読するからです。

• ポリシーはフェイルクローズでテスト可能。 evaluateUrl は、脅威テーブル全体をテストファイルに持つ純粋関数です；サーバーはポリシーが許可する前にブラウザを呼び出すことは決してありません。

スタック

TypeScript · @modelcontextprotocol/sdk（stdio） · playwright-core（CDPクライアントのみ—バンドルブラウザなし） · zod · vitest。

ライセンス

MIT © Brandon Ta