Claude Code に Playwright MCP を追加済みなのにページが開けないからといって、まずすべてを再インストールするのが最善とは限りません。MCP のセットアップでつまずく原因は、たいていいくつかのよくある問題に集約されます。プロジェクトレベルの MCP サーバーがまだ承認されていない、起動コマンドが間違っている、必要なブラウザバイナリが欠けている、のいずれかです。
まず /mcp を実行して、サーバーが接続されているか、Playwright のツールが利用できるかを確認します。次に、エージェントにページを開かせてみてください。こうすれば、問題が MCP の接続、Playwright 自体、ブラウザ環境のどこにあるのかを絞り込めます。すでに正しいかもしれない設定を何度も変更せずに済みます。
ただし、ページを開くのは最初の一歩にすぎません。実際のブラウザ作業では、検索し、複数のページを開き、異なる情報源を行き来し、ページに表示された内容に応じて次に何をするかを判断することがよくあります。たとえばエラーの調査では、検索結果を確認し、関連する複数のディスカッションを開き、報告された環境やエラーメッセージを比較し、提示された修正を検討してから、どれを試す価値があるかを判断する必要があるかもしれません。
ego (lite) なら、エージェントはこれらのページを開いたまま、あなたが使っているブラウザウィンドウを邪魔することなく、別のブラウザ Space の中で作業を続けられます。いつでもその Space に入って、エージェントが見つけた内容を確認したり、人の判断が必要なときに操作を引き継いだりできます。
本記事では、まず Claude Code での MCP の設定と、よくある Playwright およびブラウザの問題のトラブルシューティングから始めます。そのうえで、同じ調査タスクを使って、ブラウザワークフローの別のアプローチを実演します。MCP サーバーに “connected” と表示されるのは、ツールが利用可能であることを示すだけです。重要なのは、エージェントがそれらを実際に使って、次に来るブラウザタスクを完了できるかどうかです。
MCP サーバーは Claude Code に何を追加するのか？
Claude Code には独自の組み込みツールがありますが、Model Context Protocol サーバーを使うと、既定では持たない名前付きの機能を追加できます。ブラウザ、データベース、SaaS の API などです。公式の Claude Code ドキュメントは、サーバーを外部ツールやデータソースに接続する手段として説明しており、claude mcp add で追加し、セッション内では /mcp で管理します。
プロトコル自体は modelcontextprotocol.io で定義されており、トランスポートと機能はそこで規定されています。
これらのコマンドの背景にある CLI リファレンスは、公式の Claude Code MCP ドキュメント。
接続は JSON-RPC 2.0 で行われます。Claude Code がホストとなり、MCP サーバーはサブプロセス（stdio）または到達可能なエンドポイント（HTTP）として動作し、各ツールは名前、説明、入力スキーマを持ち、モデルは呼び出す前にそれを読みます。スキーマがあるからこそ、設定ミスのあるサーバーはクラッシュではなくツールが見つからない形で失敗します。接続は開くものの、ツールが検出されないのです。
サーバーはプラグインでも拡張機能でもありません。プラグインが MCP サーバーを同梱することはありますが、サーバーを直接追加すると MCP 設定に 1 つのエントリが書き込まれます。同じツールがプラグイン由来と自分の設定由来で二重に現れ、引数が異なる場合、この違いが効いてきます。
local、project、user のどのスコープを選ぶべきか？
Claude Code は MCP サーバーをスコープで解決し、スコープは設定の保存場所と、他に誰が読み込めるかという 2 つを同時に決めます。習慣ではなく、そのサーバーをどう配布したいかで選んでください。
| スコープ | 保存場所 | 参照できる範囲 | 向いている用途 |
|---|---|---|---|
| local（既定） | プロジェクトパス配下の ~/.claude.json | 現在のプロジェクトのみ。共有されない | 1 つのリポジトリだけで使いたいプライベートなサーバー。 |
| project | プロジェクトルートの .mcp.json | 現在のプロジェクトのみ。バージョン管理で共有される | チーム全体で使うサーバーを 1 つの設定に固定したいとき。 |
| user | ~/.claude.json | すべてのプロジェクト。共有されない | どこでも使いたい個人用サーバー。 |
同じサーバー名が複数のスコープに現れると、Claude Code は優先度が最も高いエントリをそのまま採用します。local は project に、project は user に優先し、勝ったエントリが他とマージされることはありません。古い user スコープのエントリが、project のエントリを黙って覆い隠すことがあります。
MCP サーバーを追加して確認するには？
ローカルの stdio サーバーは claude mcp add で追加し、-- を使って Claude Code 自身のフラグと、起動するサーバーコマンドを区切ります。ダブルダッシュより後の内容は Claude Code のオプションとして解釈されません。
claude mcp add --scope project playwright -- \
npx --yes @playwright/mcp@latest --isolatedリモートの HTTP サーバーでは、トランスポートとエンドポイントを指定します。url はあるのに type がない JSON エントリは設定エラーなので、設定を手書きするときは type を明記してください。
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp追加と確認は別の作業です。claude mcp list はサーバーごとのヘルス状態を表示し、claude mcp get はサーバー名を渡すと、失敗があればその詳細を出力します。セッション内では /mcp が接続済みサーバー、そのツール数、認証や承認が必要なサーバーを一覧表示します。
claude mcp list
claude mcp get playwrightConnected と表示されてもツールを公開していないサーバー、あるいは Failed to connect とエラーコードを表示するサーバーは、確認を通過していません。保存された設定はチェックの始まりであって、終わりではありません。
プロジェクトサーバーはいつ承認を求めるのか？
.mcp.json ファイル由来のプロジェクトスコープのサーバーは、対話型の Claude Code セッションが初めて使おうとしたときに承認を求めます。これは意図的な挙動です。リポジトリにファイルがあるからといって、コミットされた設定が黙ってブラウザ制御をエージェントに渡してよいわけではありません。
非対話の実行ではルールが変わります。claude -p、Agent SDK セッション、クラウドセッションでは表示できるプロンプトがないため、Claude Code はプロジェクトスコープのサーバーを確認なしで読み込みます。ローカルで信頼している設定が CI ではより広い攻撃面になり得るのは、これが理由です。
| 実行の種類 | 承認の挙動 | 注意点 |
|---|---|---|
| 対話セッション | プロジェクトサーバーの使用前に確認を求める | Pending approval はクラッシュではなく信頼状態です。 |
| claude -p / Agent SDK / クラウド | プロンプトなしでプロジェクトサーバーを読み込む | コミットされた .mcp.json が人のゲートなしで動作します。 |
| 信頼されていないワークスペース | フォルダを信頼するまで、リポジトリにチェックインされた承認は無視される | claude を実行して承認するまで、サーバーは Pending approval のままです。 |
特定のプロジェクトサーバーを絶対に読み込みたくない場合は、disabledMcpjsonServers に追加します。明示的に渡したサーバーだけから始めたい場合は、--strict-mcp-config を使います。どちらも意図的な制御であり、信頼プロンプトの目くらましではありません。
Playwright MCP に本当に必要な修正は何か？
Playwright MCP は Claude Code に接続される最も一般的なブラウザサーバーで、その障害は 3 か所に集中します。いずれにも再インストールより有効な修正があります。
ここにあるすべての例で使うサーバーは microsoft/playwright-mcp で、ツール一覧と未解決の issue はそこで確認できます。
これがラップしている API のドキュメントは playwright.dev。
どのブラウザサーバーを接続するかまだ決めかねているなら、Claude Code 向けのブラウザ MCP 比較が選択肢を比較しています。
既存のサーバーを修復するのではなくクリーンなマシンから始める場合は、Claude Code と Cursor のための Playwright MCP セットアップガイドがインストールと登録の手順を順を追って説明しています。
Windows: npx が stdio パイプを壊す
Windows では npx は npx.cmd であり、Claude Code がシェルを介さずに起動するバッチのラッパーです。MCP が依存する stdio パイプがつながらず、サーバーは Connection closed を報告します。ドキュメントに記載された回避策は、cmd が実行するようにコマンドをラップするか、パッケージの cli.js に対して node を直接呼び出すことです。
claude mcp add --scope user playwright -- cmd /c npx @playwright/mcp@latest{
"mcpServers": {
"playwright": {
"command": "node",
"args": ["C:\\path\\to\\node_modules\\@playwright\\mcp\\cli.js"]
}
}
}ツールが見つからない、または古いパッケージ名
正しいパッケージは @playwright/mcp です。古い @modelcontextprotocol/server-playwright は非推奨で、@executeautomation/playwright-mcp-server は別のコミュニティプロジェクトです。接続は開くのにツールが現れない場合は、自分が入力したつもりの名前ではなく、Claude Code が実際に起動しているパッケージを確認してください。
Playwright MCP にはブラウザバイナリも必要です。サーバーは起動するのに起動処理が失敗する場合は、npx playwright install を実行し、Linux や Docker では npx playwright install-deps も追加します。公式ドキュメントが示す Node.js 要件はページによって異なり、README では 18 以上、はじめかたガイドでは 20 以上なので、目の前のページと node --version を確認してください。
落ちたまま復帰しないサーバー
Claude Code は stdio サーバーを自動再接続しません。サブプロセスが死ぬとサーバーは失敗として記録され、/mcp から手動で再接続します。ブラウザタブのクラッシュやノート PC のスリープでタスクの途中にサーバーが落ちた場合、必要なのは再インストールではなく再接続です。
MCP から CLI や実ブラウザに切り替えるべき場面は？
エージェントループの内部で構造化ツールを使いたい場合、戻り値としてスナップショットを伴うブラウザ操作がほしい場合、名前で Claude Code が推論できるツールがほしい場合は MCP を維持します。タスクがシェル向き、スクリプト、保存した出力ファイル、エージェントループなしでそのまま再実行したい実行である場合は、Playwright CLI に移ります。
既存の Chrome セッションで同じ種類の障害が起きる場合は、Chrome DevTools MCP: セットアップ、既存セッション、修正が手順を追って解説しています。
サーバーを接続するとコンテキストも消費します。MCP のトークン使用量を減らす方法がそのトレードオフを解説しています。
承認済みのログイン状態が必須要件なら、実ブラウザのルートに切り替えます。新規の分離された Playwright プロファイルは普段使っている Chrome のセッションを引き継がず、MCP のフラグだけでそれを変えることはできません。
エージェントが選べるブラウザルートをもっと幅広く知りたい場合は、Claude Code にブラウザを持たせる 5 つの方法が、セットアップコストとログイン状態の挙動を比較しています。
同じ調査プロンプトを、1 台のマシンでこれらのルートのうち 2 つ、つまり設定済みの Playwright MCP サーバーと、ego-browser CLI で動く独立したブラウザ Space で実行しました。プロンプトはリポジトリの README、インストールコマンド、Node.js 要件、および次の 3 つのテーマに関する最大 3 件の issue を求めました。3 つのテーマは Connection closed、npx、stdio です。それぞれに環境、問題、回避策を添えます。両方の実行は最終的に 3 件の issue を報告しましたが、同じ 3 件ではありませんでした。
MCP ルートはまずリポジトリを読み、README と Node.js 18 の要件を確認してから Issues タブに進みました。そこでは各 issue を保存した DOM ダンプとして読み、シェルのテキストツールで必要な項目を抜き出しました。3 分 40 秒の時点で 2 件目の issue を開いており、実行は約 7 分 15 秒で終了し、issue は 1385、1540、1611 でした。
実ブラウザルートは、ページをダンプせずにその場のライブ DOM に問い合わせ、2 つ目の Space を開いて検索結果と issue ページを同時に表示したままにしました。3 分 3 秒の時点で有力な候補を確定し、4 分 11 秒に 3 件目の issue のリポジトリ注意書きに到達しました。報告したのは 658、1540、1385 です。
重複しているのは 1540 と 1385 です。重複よりも違いの方が重要です。658 は、複数の報告者が確認した唯一の設定回避策を含むスレッドで、MCP の実行はそれを拾い上げませんでした。実ブラウザの実行は内容が薄い候補を 1 件落とし、一方で MCP の実行は、報告者自身がそのリポジトリには該当しないとしてクローズした issue を残しました。これは速度の違いではなく情報源の違いであり、ストップウォッチではなくルートを選ぶべき正直な理由です。
| この実行で観測されたこと | Playwright MCP ルート | 実ブラウザルート |
|---|---|---|
| ページの読み方 | スナップショットをファイルに保存し、シェルのテキストツールで読み戻す | 開いたままのページ内でライブ DOM に問い合わせる |
| 2 件目の issue を開いた時点 | 3 分 40 秒 | 3 分 3 秒。候補を確定済み |
| 3 件目の issue に到達した時点 | 5 分 45 秒時点でもまだ読み込み中 | 4 分 11 秒。レポート作成はすでに進行中 |
| 報告した issue | 1385、1540、1611 | 658、1540、1385 |
| 有効な設定修正を含んでいた | いいえ | はい。issue 658 |
| 実行中に可視で中断可能 | いいえ。ツールの活動のみ | はい。両方の Space が画面に表示され、操作を引き継ぐコントロールもある |
| ルート | できること | 前提できないこと |
|---|---|---|
| MCP サーバー | 名前付きのツールとライブなページの根拠を Claude Code に公開します。 | 既定では、永続的なテストスイートになったり、個人の Chrome の状態を引き継いだりすることはありません。 |
| Playwright CLI | 簡潔なシェルコマンドを実行し、選択的に読むためのスナップショットや出力ファイルを保存します。 | シェルとファイルシステムにアクセスできないクライアントでは実行できません。 |
| 実ブラウザルート | 適格で承認済みの状態を備えた独立したブラウザワークスペースを操作します。 | Playwright Test のフィクスチャ、アサーション、ネットワークモック、トレースは提供しません。 |
インターフェースとコンテキストコストの全比較は、Playwright MCP vs CLI. このページは Claude Code の設定と Playwright の修正に焦点を絞っています。
ego (lite) が向く場面と向かない場面
ego (lite) は、MCP 接続自体が問題ではない作業向けの、別の実行ルートです。ego-browser スキルを通じて、独立した Space で実際の Chromium ブラウザを操作し、適格なユーザー承認済みの状態を再利用できます。ログイン済みセッション、目に見える手順、実行途中の人手による引き継ぎが必要なタスクでは、これが効いてきます。
ワークフローは 1 回の JavaScript ラウンドであり、長い MCP ツール呼び出しの連続ではありません。Space を一度開いたら、本来は 1 ブラウザ操作ずつ実行するチェックをまとめて実行します。
ego-browser nodejs <<'EOF'
const task = await taskSpace("article-qa");
for (const [slug, url] of Object.entries({
home: "https://lite.ego.app/",
mcpConfig: "https://lite.ego.app/article/claude-code-mcp-configuration"
})) {
const page = await task.newPage();
await page.goto(url, { waitUntil: "domcontentloaded" });
const report = await page.evaluate(() => ({
h1: document.querySelectorAll("h1").length,
horizontalOverflow: document.documentElement.scrollWidth > innerWidth
}));
console.log(slug, report);
}
await task.finish({ keep: [] });
EOFこのパターンは私たち自身の公開パイプラインですでに動いています。2026 年 9 月 10 日には、1 つの Space に 8 つの記事ページを開いたまま、デスクトップと 390 ピクセルのモバイルレイアウトを同時にチェックしました。canonical、言語タグ、H1 が 1 つであること、見出しの順序、画像の読み込みと alt テキスト、アンカーのターゲット、コードのはみ出し、横方向のはみ出しを確認し、その後で記事の目次をクリックして、対象の見出しがビューポートに入ることを検証しました。
これは MCP サーバーでも、Playwright Test のランナーでも、Claude Code のプラグインでもありません。エージェントに、承認済みのライブ状態を持つ検査可能なブラウザワークスペースが必要なときに使います。アサーションの多い E2E スイート、ネットワークモック、トレース成果物、ヘッドレス CI には Playwright を使い続けてください。
よくある質問
Claude Code に MCP サーバーを追加するには？
claude mcp add を使い、-- で Claude Code のフラグとサーバーコマンドを区切ります。--scope project または --scope user を意図的に指定し、claude mcp list か /mcp で確認します。
Claude Code は MCP 設定をどこに保存するのか？
local と user スコープは ~/.claude.json に保存されます。project スコープはプロジェクトルートの .mcp.json ファイルに保存され、バージョン管理にコミットできます。
Claude Code が Pending approval と表示するのはなぜか？
プロジェクトスコープの MCP 設定は、対話セッションで信頼の承認を必要とします。信頼したプロジェクトで Claude Code を開き、コマンドを確認して承認してください。
プロジェクトサーバーは CI で承認を求めるのか？
いいえ。claude -p、Agent SDK、クラウドセッションはプロンプトを表示できないため、プロジェクトスコープのサーバーを確認なしで読み込みます。コミットされた .mcp.json は、対話以外の利用ではより広い攻撃面になると考えてください。
Playwright MCP が Windows で Connection closed で失敗するのはなぜか？
Windows の npx は npx.cmd で、シェルなしでは Claude Code がその stdio パイプを使えません。コマンドを cmd /c でラップするか、パッケージの cli.js に対して node を呼び出してください。
Playwright MCP の正しいパッケージ名は？
@playwright/mcp が公式パッケージです。古い @modelcontextprotocol/server-playwright は非推奨で、@executeautomation/playwright-mcp-server は別のコミュニティプロジェクトです。
Playwright MCP に必要な Node.js のバージョンは？
公式ページでも見解が分かれています。README は 18 以上、はじめかたガイドは 20 以上としています。どちらを信じる前に、node --version と実際に読んでいるページを確認してください。
Playwright MCP は既存の Chrome ログインを使うのか？
既定では使いません。ブラウザの状態は、分離モード、ユーザーデータディレクトリ、ストレージ状態、または別途設定する実ブラウザルートによって決まります。
Claude Code では MCP、CLI、実ブラウザのどれを使うべきか？
エージェントループ内の構造化されたブラウザツールには MCP を使います。ファイル成果物を伴うシェル中心のタスクには CLI を使います。承認済みのログイン状態が要件なら実ブラウザルートを使います。
ego (lite) は Playwright MCP を置き換えられるのか？
MCP 連携をそのまま置き換えるものではありません。ego (lite) は、エージェントに専用の独立した Space を与え、既存のログイン状態を引き継ぐ別個の Chromium ブラウザであり、MCP サーバーの接続自体は問題なくても、その背後にあるブラウザセッションが障害になるタスクをカバーします。MCP サーバーではなく、Playwright MCP を置き換えるものでもありません。
