zen-mcp

zen-mcp

Zen Browser 用の初の MCP サーバーです。Claude Code、Cursor、または任意の MCP クライアントから Zen を自動操作できます。

Selenium は不要です。Playwright も不要です。ブラウザードライバーも不要です。WebSocket だけで動作します。

セットアップ（2 分）

1. リモートデバッグを有効にして Zen を起動する

/Applications/Zen.app/Contents/MacOS/zen --remote-debugging-port 9222

ヒント：シェルの設定ファイルに alias zen='open /Applications/Zen.app --args --remote-debugging-port 9222' を追加します。あとは zen を実行するだけです。

2. Claude Code に追加する

# Option A: npm (recommended)
npm install -g zen-mcp

# Option B: Clone
git clone https://github.com/sh6drack/zen-mcp.git && cd zen-mcp && npm install

~/.claude/mcp_servers.json に追加します：

{
  "mcpServers": {
    "zen-browser": {
      "command": "zen-mcp"
    }
  }
}

npm install ではなくクローンした場合は、"command": "node", "args": ["/absolute/path/to/zen-mcp/server.mjs"] を使用します。

~/.claude/settings.json に追加します：

{
  "permissions": {
    "allow": ["mcp__zen-browser__*"]
  }
}

これで完了です。 Claude Code の新しいセッションを開始すると、zen_* ツールを使用できます。

20 個のツール

閲覧

ツール	機能
zen_navigate	URL に移動します
zen_list_pages	開いているタブをすべて一覧表示します
zen_select_page	タブを切り替えます
zen_new_tab	新しいタブを開きます
zen_close_tab	タブを閉じます

表示

ツール	機能
zen_snapshot	セレクター付きでページ構造を取得します（フィルター：all/interactive/form）
zen_screenshot	スクリーンショットを撮影します
zen_get_page_text	ページのタイトル、URL、テキストを取得します
zen_get_form_fields	ラベルと値を含むすべてのフォームフィールドを一覧表示します

操作

ツール	機能
zen_click	要素をクリックします
zen_fill	入力欄またはテキストエリアに入力します
zen_select_option	ドロップダウンの項目を選択します
zen_check	チェックボックスまたはラジオボタンを切り替えます
zen_press_key	キーボード入力（Enter、Tab、Ctrl+A など）
zen_fill_form	複数のフィールドにまとめて入力します
zen_scroll	ページまたは要素までスクロールします

ユーティリティ

ツール	機能
zen_evaluate	ページ内で JavaScript を実行します
zen_wait	指定したミリ秒数だけ待機します
zen_wait_for	テキストまたは要素が表示されるまで待機します
zen_reconnect	Zen への再接続を強制します

仕組み

Claude Code  ──stdio/MCP──>  zen-mcp  ──WebSocket/BiDi──>  Zen Browser

zen-mcp は WebSocket 経由で WebDriver BiDi（W3C 標準）を直接使用します。フォームへの入力では、ネイティブの値セッターを使い、input／change イベントをディスパッチするため、React、Vue、Angular のアプリでも正しく動作します。

正常に動作する機能

• ナビゲーション、クリック、フォーム入力 — 安定して動作し、React／Vue／Angular に対応します
• スクリーンショットとページの読み取り — 信頼性の高いコンテンツ抽出が可能です
• タブ管理 — タブを開く、閉じる、切り替えることができます
• JavaScript の評価 — ページのコンテキスト内で任意のコードを実行できます
• キーボード入力 — ショートカット、Enter、Tab、修飾キーの組み合わせに対応します

既知の制限事項

• Zen は Firefox の WebDriver BiDi 実装を継承しており、現在も開発が進んでいます。Chrome で使える一部の高度な BiDi コマンドは、まだ利用できない場合があります。
• ゾンビセッションを解消するには、Zen の再起動が必要です（BiDi の session.end は接続単位です）。zen-mcp はこれを検知し、必要な操作を案内します。
• ファイルのアップロードとドラッグ＆ドロップには対応していません（BiDi 仕様の制限です）。

標準搭載の信頼性機能

• WebSocket が切断された場合、指数バックオフで自動再接続
• 前のクライアントがクラッシュした場合のゾンビセッションの復旧
• 接続の再試行（バックオフを伴う 3 回の試行）
• 孤立したセッションを防ぐ、SIGINT／SIGTERM 時のクリーンシャットダウン

トラブルシューティング

問題	対処方法
「Zen Browser に接続できません」	--remote-debugging-port 9222 を指定して Zen を起動します
「アクティブなセッション数が上限に達しました」	Zen を再起動します：killall zen && zen
接続が繰り返し切断される	zen_reconnect を使って新しい接続を強制します

設定

環境変数	デフォルト	説明
ZEN_DEBUG_PORT	9222	Zen のリモートデバッグポート

要件

• Zen Browser
• Node.js 20+

テスト

node test-e2e.mjs   # 21 tests, needs Zen running

ライセンス

MIT