feder-cr/invisible_playwright_mcp — 優良食堂詳しい解説

01 / 概要

何をするものか一文で言うと

ひとことでブラウザ自動化AIエージェント。反ボット検知を回避してWebページを操作します。

invisible_playwright_mcpは、ステルス化したFirefoxをPlaywright経由で操作するMCPサーバーです。アンチボット検知やキャプチャに引っかかりにくい状態で、AIエージェントがウェブページを操作します。Claude CodeやCodex、Gemini CLIへのプラグイン追加に加え、OpenRouterキーで動くスタンドアロンのWeb UIとしても使えます。

02 / 構造

どう動くのか中核のしくみ

読み方動きの流れを図と一緒にほどきました。

MCPサーバーはmcpライブラリのFastMCPで構築されており、browser_navigateやbrowser_click_at、browser_watchといったツールをLLMに公開します。実際のクリックや入力操作は、Playwright互換APIを持つinvisible_playwrightという別パッケージのエンジンが担当します。pyproject.tomlの依存コメントを見ると、下限バージョンの指定理由が実際に起きた不具合の修正履歴としてそのまま書かれています。例えば0.22.1未満では、クリック後に再判定が走る仕組みのせいで、モーダルを閉じる操作が1,068回誤実行された事例が記録されています。cli.pyのuiサブコマンドは、SessionsとLinkという仕組みで会話エンジンとブラウザエンジンをつなぎます。そこをuvicornが配信し、ブラウザ映像と会話はWeb UI画面に並びます。agent.pyのConversationクラスが、LLM呼び出しとツール呼び出しを繰り返すループ本体です。--proxyを渡すと、タイムゾーンやロケール、通信経路がそのプロキシに合わせて切り替わる設計です。

03 / 体験

入れるとこんな体験になりますギット飯が実際にたどった順序

所要ギット飯が実際に導入・実行しながらたどった順序です。

STEP 01
uvをインストールし、Claude CodeやCodex、Gemini CLIなどのアシスタントにプラグインマーケットプレイスを追加すると、invisible-playwright-mcpがツールとして登録されます。
STEP 02
最初にbrowser_openツールを呼ぶと、STEALTHFOX_BINARYや--binaryを指定していない場合はステルスFirefoxバイナリのダウンロードが走り、数百MB規模の待ち時間が発生します。
STEP 03
自然文で航空券検索のようなタスクを渡すと、エージェントがbrowser_navigateやbrowser_click_atを繰り返し呼び出しながらページを操作する様子がログに記録されます。
STEP 04
uvx invisible-playwright-mcp ui --openrouter-key ...を実行してhttp://127.0.0.1:8765を開くと、左側にチャット、右側にライブブラウザ映像が並ぶWeb UIが表示されます。
STEP 05
--seedや--profile-dirを指定すると、再実行しても同じブラウザ識別子やログイン状態が保たれることを確認できます。
STEP 06
macOS環境で試すと、classifiersにWindowsとLinuxしか記載がないため、エンジンバイナリが提供されずbrowser呼び出しの時点で失敗することに気づきます。

04 / 成果物

何が手に入るのか導入後に手元に残るもの

実行して得られるのは、自然言語の指示で動くブラウザ操作エージェントです。MCPツール経由ならページ遷移やクリック、入力の実行ログとスクリーンショットが、Web UI経由ならチャット画面とライブブラウザ映像が手元に残ります。articlesディレクトリのmystery-books.csvやprices.csvのように、実際にサイトから抽出したCSVや検証用スクリプトも成果物として確認できます。--seedや--profile-dirを使えば、同じブラウザ識別子とログイン状態を次回以降も再利用できます。

05 / 注意

ここは先に知っておいてください先に知っておくとよいこと

正直なところ誰にでも合うとは言いにくいところです。

classifiersにはWindowsとPOSIX Linuxしか記載がなく、macOSではエンジンバイナリが提供されない可能性があります。

--hostを127.0.0.1以外に変更すると、認証なしのWeb UIがネットワークに公開されてしまいます。

--openrouter-keyをコマンドライン引数で渡すと、シェル履歴やLinuxのプロセスリストにキーが残ります。

依存バージョンは下限指定のみで上限は緩く、uvxのキャッシュ環境では過去の既知バグを含むバージョンが残る場合があります。

06 / 結論

ギット飯の結論食べてみる価値のある一膳か

ギット飯の最終判断優良食堂

見積もりや予約の空き確認、フォーム入力など、人が実際にページを見て判断しながら操作する作業を自動化したい開発者に向いています。MCPクライアントに組み込んで使うエンジニアと、OpenRouterキーだけで試したい非エンジニアの両方を想定した設計です。pyproject.tomlの依存コメントには、実際に起きた不具合とその修正バージョンが日付付きで記録されており、README本文もオプションの優先順位やセキュリティ上の注意を具体的に説明しています。これらの記述は推測ではなく実装とコメントに基づいているため、インストールして試す前の判断材料として十分に信頼できます。