WaveXisMCP

MCP サーバー — LLM 向けブラウザー自動化ツール 220 種

Chrome + Firefox · CDP + BiDi · 100% Python · Node.js 不要 · Chromium のダウンロード不要

---

英語 | 简体中文 | 日本語

wavexis ブラウザー自動化ライブラリを LLM に公開する MCP サーバーです。13 の機能階層にわたる 220 種のツールを提供します。Node.js も Chromium のダウンロードも不要で、既存の Chrome／Edge を使用します。100% Python です。

クイックデモ

最初のスクリーンショットまで 30 秒。 MCP クライアントの設定（Claude Desktop、Cursor、Windsurf、VS Code）に次の内容を追加します。

{
  "mcpServers": {
    "wavexis": {
      "command": "uvx",
      "args": ["wavexis-mcp", "--caps", "all"]
    }
  }
}

次に、LLM に次のように尋ねます。

「https://example.com のページ全体のスクリーンショットを撮って」

LLM は wavexis_screenshot(url="https://example.com", full_page=true) を呼び出し、スクリーンショットを返します。Node.js も Chromium のダウンロードも不要で、上記の設定以外にセットアップは必要ありません。

WaveXisMCP を選ぶ理由

WaveXisMCP は wavexis ブラウザー自動化ライブラリをラップし、MCP サーバーとして公開します。Node.js、Playwright、または Chromium の別途ダウンロードは不要です。WaveXisMCP は既存の Chrome または Edge を直接起動します。

主な機能

• 220 種のツール — Playwright MCP（21）の 3 倍、zendriver-mcp（96）の 2 倍
• 13 の機能階層 — --caps で必要な機能だけを有効にできます。まず core（72 種のツール）から始め、必要に応じて階層を追加します
• Chrome + Firefox — Chrome／Edge には CDP、Firefox には BiDi を使用します。どちらも PATH からドライバーを自動起動します
• Chromium のダウンロード不要 — 既存のブラウザーを使用します。インストールサイズは約 5MB で、Playwright MCP の約 400MB より小さくなっています
• ステルスモード — stealth=true により navigator.webdriver を隠し、プラグイン、言語、Chrome ランタイムを偽装します
• 構造化されたエラー — すべてのエラーに suggestion フィールドが含まれるため、人の助けなしで LLM が自己修正できます
• 複数アクションの YAML — ナビゲーション → クリック → 入力 → スクリーンショットを 1 回のツール呼び出しで連鎖できます
• CDP／BiDi の直接アクセス — 専用ツールで対応していないブラウザー機能にもアクセスできます
• Lighthouse 監査、WebAuthn、Bluetooth、Cast — 他の MCP サーバーでは扱っていないニッチな機能です
• SSRF 保護、パスのサンドボックス化、レート制限 — 初日からセキュリティを組み込んでいます
• 700 件以上のテスト、90% のカバレッジを強制、実際の Chrome を使った E2E テスト — 本番環境に対応しています

仕組み

You (natural language)
  → LLM decides which tool to call
    → WaveXisMCP receives the tool call
      → wavexis library executes it via CDP or BiDi
        → Chrome/Edge/Firefox performs the action
      ← Result returned as JSON (text, base64, file path)
    ← JSON passed back to LLM
  ← LLM summarizes the result for you

LLM がブラウザーを直接見ることはありません。見るのはツール定義（名前、説明、パラメーター）と JSON レスポンスだけです。そのため、MCP 対応の LLM クライアントであれば、カスタム統合なしですぐに動作します。

コアコンセプト

• ツール — スクリーンショット、評価、クリックなど、MCP ツールとして公開され、あらゆる LLM クライアントから呼び出せる単一のブラウザー操作です。
• セッション — 永続的なブラウザーインスタンスです。セッションを開き、複数のツール呼び出しを連続して実行し、完了したら閉じます。操作ごとにブラウザーを起動するオーバーヘッドを回避できます。
• ステートレスモード — url パラメーターを指定して任意のツールを呼び出します。ブラウザーは自動的に起動し、処理を実行して終了します。
• 機能ティア — core（72 個のツール）から all（220 個のツール）まで、13 段階のティアがあります。--caps を使って必要な機能だけを有効にできます。
• デュアルバックエンド — CDP（cdpwave 経由の Chromium ネイティブ）と BiDi（bidiwave 経由の W3C クロスブラウザー）に対応し、セッションごとに選択できます。
• 構造化エラー — すべてのエラーに、LLM に次の操作を伝える suggestion フィールドが含まれているため、人の介入なしに自己修正できます。

インストール

pip install wavexis-mcp

CDP バックエンド（Chromium）はデフォルトで含まれています。BiDi バックエンド（Firefox）を使用する場合：

pip install "wavexis-mcp[bidi]"

または、インストールせずに実行します（推奨）：

uvx wavexis-mcp

要件

• Python：3.11、3.12、または 3.13
• ブラウザー：Google Chrome、Microsoft Edge、または Chromium／Chrome ベースのブラウザー
• BiDi バックエンド（任意）：Chrome 用の ChromeDriver／EdgeDriver、または Firefox 用の geckodriver

クイックスタート

MCP クライアントの設定（Claude Desktop、Cursor、Windsurf、VS Code）に追加します：

{
  "mcpServers": {
    "wavexis": {
      "command": "uvx",
      "args": ["wavexis-mcp", "--caps", "all"]
    }
  }
}

または、pip を使用します：

{
  "mcpServers": {
    "wavexis": {
      "command": "wavexis-mcp",
      "args": ["--caps", "all"]
    }
  }
}

ステートレスモード（単発実行）

url パラメーターを指定して任意のツールを呼び出します。ブラウザーは自動的に起動し、処理を実行して終了します：

wavexis_screenshot(url="https://example.com", full_page=true)

セッションモード（複数ステップ）

セッションを開き、複数の操作を連続して実行し、完了したら閉じます：

wavexis_session_open(backend="cdp", headless=false)
→ {"session_id": "abc-123"}

wavexis_navigate(session_id="abc-123", url="https://example.com")
wavexis_click(session_id="abc-123", selector="#login")
wavexis_screenshot(session_id="abc-123")
wavexis_session_close(session_id="abc-123")

自然言語での操作（M1）

wavexis_act を使って、自然言語でページを操作します：

wavexis_session_open(backend="cdp")
wavexis_navigate(session_id="abc-123", url="https://example.com")
wavexis_act(session_id="abc-123", instruction="click the login button")
→ {"action": "click", "element": {"ref": "el-3", "role": "button", "name": "Login"}, "status": "ok"}

wavexis_act ツールは a11y スナップショットを取得し、キーワードのスコアリングによって指示を要素に照合して、検出した操作（クリック、入力、値の設定、ホバー）を実行します。外部 LLM の呼び出しは不要で、ヒューリスティックによる照合のみで動作します。

機能ティア

ティア	フラグ	ツール	主な機能
コア	常時有効	72	セッション、ナビゲーション、スクリーンショット、PDF、スクレイピング、評価、DOM、入力、Cookie、タブ、自然言語操作、iframe、シャドウ DOM、イベント
ネットワーク	--caps=network	20	ヘッダー、UA、ブロック、スロットリング、キャッシュ、HAR、インターセプト、モック、リクエスト／レスポンスの変更、リクエスト本文、HAR の再生、リクエスト一覧
ストレージ	--caps=storage	18	localStorage、sessionStorage、キャッシュストレージ、IndexedDB、状態の保存／復元
エミュレーション	--caps=emulation	9	デバイス、ビューポート、位置情報、タイムゾーン、ダークモード、ロケール、CPU、タッチ、センサー
A11y	--caps=a11y	4	アクセシビリティツリーのスナップショット、ノードの走査、axe-core による監査
インタラクション	--caps=interactions	5	ダイアログ、ダウンロード、権限
DevTools	--caps=devtools	31	パフォーマンス、CSS、デバッグ、オーバーレイ、コンソール、セキュリティ、ウィンドウ管理、統合トレース、注釈付きスクリーンショット
ビジョン	--caps=vision	7	座標ベースのマウス操作（ピクセル単位の精度）
ビデオ	--caps=video	4	ビデオ録画、チャプター、アクションオーバーレイ
テスト	--caps=testing	6	アサーション、ロケーターの生成
ワークフロー	--caps=workflows	6	複数アクションの YAML、生の CDP／BiDi、ブラウザーコンテキストの CRUD
データ	--caps=data	7	コード生成、Lighthouse 監査、抽出、WebSocket インターセプト、クロール、視覚的差分、Core Web Vitals
実験的機能	--caps=experimental	31	サービスワーカー、アニメーション、WebAuthn、WebAudio、メディア、キャスト、Bluetooth、拡張機能、設定
合計	--caps=all	220

デフォルト：--caps=core（72 個のツール）。すべて有効にするには：--caps=all。特定の機能を有効にするには：--caps=network,storage,emulation。

ヒント：まずは --caps core から始め、必要に応じてティアを追加してください。ティアを追加するたびにツール定義が LLM のコンテキストに加わり、トークンを消費します。ほとんどのタスクでは、core,network,storage（110 個のツール）がバランスのよい設定です。

バックエンド

WaveXisMCP は、機能が完全に同等な 2 つのバックエンドに対応しています。

• CDP（cdpwave） — デフォルト。Chrome DevTools Protocol です。Chrome／Edge に WebSocket で直接接続します。ドライバーは不要です。57 の CDP ドメインに対応しています。デフォルトで含まれています。
• BiDi（bidiwave） — WebDriver BiDi プロトコルです。W3C のクロスブラウザー規格に対応しています（Firefox、Chrome）。chromedriver（Chrome）または geckodriver（Firefox）が必要です。いずれも実行中でない場合は PATH から自動的に起動されます。pip install "wavexis-mcp[bidi]"

セッションごとに選択します。

# CDP (default, Chrome/Edge only)
wavexis_session_open(backend="cdp")

# BiDi with Chrome (auto-launches chromedriver)
wavexis_session_open(backend="bidi", browser="chrome")

# BiDi with Firefox (auto-launches geckodriver)
wavexis_session_open(backend="bidi", browser="firefox")

既存の Chrome に接続する

connect_existing=True を使用すると、--remote-debugging-port を指定して Chrome を起動し、接続できます。ログイン済みのセッションがあるブラウザープロファイルを再利用する場合に便利です。

# Launch Chrome with debug port and connect via CDP
wavexis_session_open(connect_existing=true)

# Reuse an existing Chrome profile (keeps logins, cookies, extensions)
wavexis_session_open(connect_existing=true, user_data_dir="C:/Users/me/ChromeProfile")

Chrome はヘッドありで起動します（ヘッドレス設定は無視されます）。セッションが閉じられると、ブラウザーのサブプロセスは終了します。

複数アクションの YAML

YAML 文字列を渡すと、1 回のツール呼び出しで複数のアクションを連続して実行できます。

wavexis_multi_action(
    config="""
actions:
  - navigate: https://example.com
  - screenshot:
      full_page: true
  - eval: document.title
  - click: "#login"
  - type:
      selector: "#username"
      text: [email protected]
  - screenshot: {}
""",
    session_id="abc-123"
)

対応しているアクションの種類は、navigate、screenshot、eval、click、type、fill です。失敗しても実行を続けるには、continue_on_error: true を設定します。

MCP リソースとプロンプト（M3）

リソース（読み取り専用のブラウザー状態）：

• wavexis://session/{id}/url — 現在のページ URL
• wavexis://session/{id}/cookies — JSON 形式の Cookie
• wavexis://session/{id}/console — コンソールメッセージ
• wavexis://session/{id}/tabs — 開いているタブ

プロンプト（ワークフローテンプレート）：

• scrape_page(url, selector) — ページをスクレイピングしてコンテンツを抽出
• audit_page(url) — アクセシビリティとパフォーマンスの包括的な監査
• fill_form(url, fields) — ページのフォームに入力
• debug_page(url) — コンソール、ネットワーク、パフォーマンスをデバッグ

HTTP トランスポート

CI/CD、共有インスタンス、Docker 向けに、WaveXisMCP を HTTP サーバーとして実行できます。

# HTTP on localhost
wavexis-mcp --transport http --port 8765

# HTTP with all tiers
wavexis-mcp --transport http --port 8765 --caps all

# HTTP with remote access (use behind a reverse proxy!)
wavexis-mcp --transport http --allow-remote --port 8765

デフォルトでは 127.0.0.1 にバインドします。0.0.0.0 を使用するには --allow-remote を指定します。

レート制限（M4）

セッションごとにトークンバケット方式でレート制限を行います。

# 10 calls/sec, burst of 5
wavexis-mcp --rate-limit 10 --rate-burst 5

制限を超えると、ツールは標準の構造化エラーを返します：{"error": "Rate limit exceeded. Retry after Nms.", "type": "RuntimeError", ...}。無効にするには --rate-limit 0 を設定します。

Docker

# Pull and run
docker run -p 8765:8765 ghcr.io/mathiaspaulenko/wavexis-mcp

# Or build locally
docker build -t wavexis-mcp .
docker run -p 8765:8765 wavexis-mcp

# Docker Compose
docker-compose up

詳細については、Docker のドキュメントを参照してください。

比較

機能	Playwright MCP	WaveXisMCP
言語	TypeScript	Python
Node.js が必要	✗	✓（Node.js 不要）
Chromium をダウンロード（約 200MB）	✓	✗（既存のブラウザーを使用）
インストールサイズ	約 400MB	約 5MB
コールドスタート	3.2 秒	0.8 秒
ツールの合計数	約 21	220
機能ティア（オプトイン）	✗	✓（13 ティア）
2 つのプロトコルに対応（CDP + BiDi）	✗	✓
Firefox に対応	✓（基本）	✓（BiDi + geckodriver の自動起動）
バックエンドの選択（セッションごと）	✗	✓
ステルス／ボット対策モード	✗	✓
CDP／BiDi への直接アクセス	✗	✓（エスケープハッチ）
複数アクションの YAML バッチ処理	✗	✓
動画録画	✗	✓
Lighthouse 監査	✗	✓
WebAuthn／Bluetooth／Cast	✗	✓
自然言語での操作	✗	✓（wavexis_act）
MCP リソースとプロンプト	✗	✓
レート制限	✗	✓
SSRF 保護	✗	✓
提案を含む構造化エラー	✗	✓

注：Playwright MCP は WebKit（Safari）に対応していますが、WaveXisMCP はまだ対応していません。予定されている機能については、ロードマップを参照してください。

ドキュメント

ドキュメント、API リファレンス、サンプルの全編は、mathiaspaulenko.github.io/wavexis-mcp で公開されています。

主なセクション：

• クイックスタート
• アーキテクチャ
• 設定
• Docker
• HTTP トランスポート
• レート制限
• ツールリファレンス
• サンプル

エラー処理

すべてのツールは、失敗時に構造化されたエラー JSON を返します。すべてのエラーには、LLM に次のアクションを案内する suggestion フィールドが含まれています：

{
  "error": "Session 'abc-123' not found.",
  "tool": "wavexis_navigate",
  "type": "SessionNotFoundError",
  "message": "Session 'abc-123' not found.",
  "suggestion": "Call wavexis_session_open first to create a browser session."
}

これにより、LLM は人間の介入なしに自己修正できます。提案を読み、推奨されたツールを呼び出します。

アーキテクチャ

WaveXisMCP は、3 層のエコシステムの最上位に位置します：

WaveXisMCP (MCP server, 220 tools)
└─ wraps → wavexis (browser automation library)
               ├─ cdpwave (CDP backend, Chromium-native)
               └─ bidiwave (BiDi backend, W3C cross-browser)

• cdpwave — Chrome DevTools Protocol 用の低レベルな非同期 Python ライブラリです。Chrome／Edge に WebSocket で直接接続します。ドライバーのバイナリは不要です。
• bidiwave — WebDriver BiDi プロトコル（W3C 標準）用の低レベルな非同期 Python ライブラリです。Firefox、Chrome、Edge で動作します。
• wavexis — cdpwave と bidiwave を統一された AbstractBackend インターフェースの背後で抽象化する、高レベルなブラウザー自動化ライブラリです。
• WaveXisMCP — wavexis をラップする MCP サーバーです。各バックエンドメソッドを、Pydantic v2 による入力検証、JSON レスポンス、機能ティアのフィルタリングを備えた MCP ツールとして公開します。

システム設計、データフロー図、ADR の全編については、アーキテクチャのドキュメントをご覧ください。

開発

git clone https://github.com/MathiasPaulenko/wavexis-mcp.git
cd wavexis-mcp
pip install -e ".[dev]"

# Run quality checks
ruff check wavexis_mcp tests
ruff format --check
mypy wavexis_mcp
python -m bandit -r wavexis_mcp

# Run tests
pytest tests/unit -v

貢献

貢献を歓迎します。開発ワークフロー、コーディング規約、プルリクエストの手順については、CONTRIBUTING.mdをご覧ください。セキュリティ上の問題については、SECURITY.mdをご覧ください。

謝辞

WaveXisMCP は、wavexis ブラウザー自動化ライブラリと Model Context Protocol を基盤として構築されています。このプロジェクトを可能にするツールや標準を提供してくださった、オープンソースの Python コミュニティおよび MCP コミュニティに感謝します。

ライセンス

MIT

mcp-name: io.github.MathiasPaulenko/wavexis-mcp