Browser MCP Server

MCP（Model Context Protocol）サーバーです。Zyte API を介して、AI エージェントに実際の、アンチボット対応ブラウザを提供します。ページの閲覧、クリック/入力/スクロール、スクリーンショットの取得、構造化データの抽出が可能で、プロキシ/IP の自動ローテーションと ban 防止を備えています。

NestJS と @nestjs-mcp/server で構築され、Zyte の /extract エンドポイントと HTTP で直接通信します。トランスポートはストリーミング対応の HTTP のみで、単一の /mcp エンドポイントでステートレスに提供されます。

セットアップ

1. .env.example を .env にコピーして、以下を設定します:

   変数	必須	説明
   ZYTE_API_KEY	はい	あなたの Zyte API キー
   ZYTE_API_BASE_URL	いいえ	Zyte API のベース URL を上書きします（既定値: https://api.zyte.com/v1）
   PORT	いいえ	HTTP ポート（既定値: 3000）
   BROWSER_TIMEOUT_MS	いいえ	Zyte への呼び出しごとのタイムアウト（既定値: 30000）
   BROWSER_MAX_RETRIES	いいえ	レート制限（429/503）と一時的な禁止（520）の応答に対する再試行回数（指数バックオフ付き）（既定値: 2）

2. 依存関係をインストールしてサーバーを起動します:

   pnpm install
   pnpm run start:dev

   MCP エンドポイントは http://localhost:3000/mcp で提供されます。

Related MCP server: Stealth Browser MCP

ツール

browser_browse、browser_screenshot、browser_extract は、任意の sessionId（以前の呼び出しで返された値）を受け取り、複数のツール呼び出しで同じ IP アドレスと Cookie jar を再利用します。ログイン状態を維持したり、複数ステップのタスク全体で一貫した IP を保つために便利です。Zyte のセッションに関するドキュメントにあるように、これは呼び出し間で実際のブラウザ/タブの状態（ページ内のフォーム入力、スクロール位置、開いているモーダルなど）を保持しません。各呼び出しでは、同じネットワーク ID と Cookie を使って新しいページが読み込まれます。

actions は結果をキャプチャする前に実行される一連のステップです: click、type、select、hover、keyPress、scrollBottom、scrollTo、waitForSelector、waitForTimeout、waitForNavigation、goto、evaluate。要素を指定するアクションには、selector: { type: "css" | "xpath", value: string } を渡します。

browser_search は Zyte の別のエンドポイント /v1/search（/v1/extract ではありません）に送信され、domain（サポートされている検索エンジン、例: "google.com"）、query、および任意の maxResults（10–100）/ geolocation / locale を受け取ります。

レート制限（429/503）と一時的な禁止（520）の Zyte からの応答は、Zyte のエラー処理ガイダンスに従って、指数バックオフで BROWSER_MAX_RETRIES 回まで自動的に再試行されます。その他のエラー応答（無効なリクエスト、恒久的な禁止、アカウント停止）は、Zyte のエラー type が取得できる場合はメッセージに含めた上で、すぐに返されます。

クライアントの接続

実行中のインスタンスを指すリモート MCP クライアント設定の例（例: Claude Desktop / Claude Code）:

{
  "mcpServers": {
    "browser": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

テスト

pnpm test        # unit tests (service + resolver, global fetch mocked)
pnpm run lint    # eslint
pnpm run build   # type-check + compile

単体テストでは、Zyte への呼び出しに使用されるグローバルな fetch をモックしています。実際の API に対するエンドツーエンドの検証を行うには、実際の ZYTE_API_KEY でサーバーを実行し、pnpm dlx @modelcontextprotocol/inspector http://localhost:3000/mcp または curl を使って、initialize → tools/list → tools/call を実行してください。