Claude Media
Claude CodeにStagehandをつないでブラウザ操作を任せる手順
Claude CodeMCPClaude連携チュートリアル

Claude CodeにStagehandをつないでブラウザ操作を任せる手順

StagehandのClaude Code連携は、プラグインではなくリポジトリをビルドして使うMCPアダプターです。登録手順、run・snapshot・screenshotの3ツール、権限の絞り方を説明します。

読了目安 約14分

Claude CodeからStagehandのブラウザを使うには、StagehandのリポジトリをビルドしてMCPサーバーとして登録します。Stagehandのドキュメントが案内するClaude Code連携は、プラグインとして配布されるものではなく、実験的な位置づけの統合です。

登録後のClaude Codeにはrun・snapshot・screenshotの3つのツールが加わります。1つのサーバープロセスがブラウザを持ち続けるので、ログインやページの状態が呼び出しをまたいで残ります。

Stagehand連携はプラグインではなくMCPアダプター

Stagehandは、Browserbaseが開発するブラウザ自動化のフレームワークです。コーディングエージェント向けには、stdioで動くMCPアダプターを用意しています。Claude Code、Codex、fx、Piのガイドが並び、Claude Codeの接続方法は「プロジェクトの.mcp.jsonに書くMCPサーバー」と説明されています。

押さえておく点が3つあります。

  • 連携は実験的で、Stagehandのリポジトリから動かす。共通のアダプターは単体パッケージとして公開されていない
  • Node.js 24以上とpnpm 11.11.0が要る。ローカルのブラウザを使うならGoogle Chromeも要る
  • ブラウザ操作の判断はClaude Code側のモデルが担う。アダプターはモデルを選ばず、置き換えもしない

「プラグインを入れる」感覚で/pluginから入れるのではなく、ビルドしたstdio-server.mjsをnodeで起動するMCPサーバーとして登録する、と理解すると迷いません。

ビルドしてClaude Codeに登録する

手順

登録までの流れ

  1. 1

    Stagehandをクローンしてビルドする

    統合パッケージだけをビルドします。

  2. 2

    stdioサーバーの場所を確かめる

    packages/integrations/core/dist/facade/stdio-server.mjsができていればビルドは成功です。

  3. 3

    Claude Codeに登録する

    同梱の.mcp.jsonを使うか、claude mcp addで自分で登録します。

  4. 4

    ブラウザの置き場所を決める

    ローカルのChromeか、BrowserbaseのクラウドかをSTAGEHAND_BROWSERで選びます。

ビルドまでの公式手順は次のとおりです。

git clone https://github.com/browserbase/stagehand.git
cd stagehand
pnpm install --frozen-lockfile
pnpm exec turbo run build \
  --filter @browserbasehq/stagehand-integrations

同梱の.mcp.jsonで試す

リポジトリのpackages/integrations/claude-codeには、プロジェクトスコープの.mcp.jsonが入っています。中身は次のとおりです。

{
  "mcpServers": {
    "stagehand": {
      "command": "node",
      "args": ["../core/dist/facade/stdio-server.mjs"]
    }
  }
}

argsのパスはパッケージからの相対なので、必ずそのディレクトリでClaude Codeを起動します。

cd packages/integrations/claude-code
claude

Claude Codeは起動したシェルの環境変数を引き継ぐため、設定はexportだけで済みます。起動後に次のように頼むと、動作確認になります。

Use Stagehand to open https://example.com and report the page title.

公式の説明では、エージェントはrunでページを開き、Example Domainを報告するはずとされています。

好きなプロジェクトで使うには

相対パスの.mcp.jsonは、そのディレクトリを離れると動きません。別のプロジェクトで使いたいときは、公式が示す設定値(コマンドはnode、引数はビルドしたstdio-server.mjsの絶対パス)を、Claude Codeのstdio登録の書式に当てはめます。例えば次のような形です。パスは自分のチェックアウト先に置き換えます。

claude mcp add --transport stdio \
  --env STAGEHAND_BROWSER=local \
  stagehand -- node \
  /absolute/path/to/stagehand/packages/integrations/core/dist/facade/stdio-server.mjs

claude mcp addは<name> -- <command> [args...]の形で、--envでサーバーの環境変数を渡せます。この書式はClaude Code側のMCPドキュメントにあります。サーバー名をstagehandにしたので、ツールはmcp__stagehand__runのような名前で呼ばれます。MCPサーバー追加の基本はClaude Code MCP設定ガイドに詳しくあります。

3つのツールでできること

アダプターが渡すツールは3つだけです。

ツールできること
runできることブラウザのpage・context・browserに対してJavaScriptを実行する。対応するスナップショット操作も行う
snapshotできること表示中のページのアクセシビリティツリーを、コンパクトな形で読む
screenshotできることページを撮影して、見た目を確認する

runには、たとえば次のような入力が渡されます。

{
  "code": "await page.goto('https://example.com'); return await page.title();"
}

使い分けは単純です。ページを動かす・値を返すのがrun、画面の構造を読むのがsnapshot、見た目を見るのがscreenshotです。スナップショットの要素IDは最新のスナップショットにだけ有効なので、ページ遷移の後や、IDが古くなったと分かったときは、取り直します。

自然言語のデータ抽出はどこへ行ったか

v3のホスト型MCPには、act・observe・extractという自然言語のツールがあります。たとえばactは「ログインボタンをクリックして」のような指示で動く仕組みです。v4のアダプターの表に出てくるのは、上の3つです。

つまりこちらの構成では、ページの読み取りと抽出はClaude Codeのモデルがsnapshotの結果を読んで行い、操作はrunのJavaScriptに落とし込みます。「ページから価格だけを表にして」のような依頼はClaude Codeに直接伝えれば足ります。

くらべる

自然言語のブラウザ操作、どちらの構成か

URLを渡すだけ

v3のホスト型MCP

act・observe・extractなどのツールが、Stagehand側のモデルで自然言語を解釈します。セットアップはAPIキーの指定が中心です。

手元でビルド

v4のstdioアダプター

run・snapshot・screenshotの3ツールだけで、解釈はClaude Code側のモデルが担います。ブラウザの状態は1つのサーバーが保持します。

ブラウザはローカルかBrowserbaseか

ブラウザの置き場所は、MCPサーバーの環境変数で決まります。

変数内容
STAGEHAND_BROWSER内容localかbrowserbase。未設定なら、BROWSERBASE_API_KEYがあるとBrowserbase、なければローカルのChrome
BROWSERBASE_API_KEY内容Browserbaseを使うときに必須
BROWSERBASE_PROJECT_ID内容任意のプロジェクトID
STAGEHAND_MODEL_NAME内容runの中で呼ぶStagehandのAIメソッド用モデル(任意)
STAGEHAND_MODEL_API_KEY内容STAGEHAND_MODEL_NAMEを指定したとき必須

BROWSERBASE_API_KEYを設定済みのシェルでClaude Codeを起動すると、何も指定しなくてもクラウドのブラウザに切り替わる点に注意が要ります。ローカルのChromeを使いたいときは、STAGEHAND_BROWSER=localを明示しておくと取り違えません。

モデルの役割分担も確かめておきます。ブラウザを動かす判断をするのはClaude Codeが使うモデルで、認証もClaude Code側のものです。アダプターが別のモデルを必要とするのは、StagehandのAIメソッドを使う場合だけで、その資格情報は別に渡します。決まった操作だけなら、Stagehand用のモデルは要りません。

権限を絞る

runは、エージェントが書いたJavaScriptを、StagehandのブラウザのService Workerで実行します。ブラウザを操作でき、そのセッションで見られるデータにも触れられます。公式はこの境界を明記し、信頼できないタスクにはBrowserbaseを使い、ツールの権限はCLIエージェント側で設定するよう求めています。ログイン済みのセッションは特権的なものとして扱う、という注意もあります。

公式の例は、ヘッドレス実行で許可するツールを3つに限っています。

claude -p "your instruction" --mcp-config .mcp.json \
  --allowedTools "mcp__stagehand__run,mcp__stagehand__snapshot,mcp__stagehand__screenshot"

対話で使うなら、snapshotとscreenshotは事前許可にして、runは毎回確認に回す構成が考えられます。Claude Codeの権限ルールにMCPツール名を書く方式の一例です。

{
  "permissions": {
    "allow": [
      "mcp__stagehand__snapshot",
      "mcp__stagehand__screenshot"
    ],
    "ask": [
      "mcp__stagehand__run"
    ]
  }
}

読むだけの2ツールは副作用が小さく、任意のJavaScriptを実行できるrunだけを人の目に通す、という考え方です。外部ツールを接続する際の全般的なリスクはMCPセキュリティガイドで扱っています。

つまずきやすい点

落とし穴

ディレクトリ違いで同梱の.mcp.jsonが読めない

argsが../core/dist/...の相対パスなので、packages/integrations/claude-code以外でclaudeを起動するとサーバーが見つかりません。別の場所から使うなら、絶対パスでの登録に切り替えます。

落とし穴

呼び出しごとにサーバーを起動し直すと別のブラウザになる

ブラウザを持つのは1つのサーバープロセスです。呼び出しのたびに新しいプロセスを起動すると、毎回新しいブラウザが立ち上がり、前のページの状態は失われます。公式のSDKの例は、queryループ全体で1つのサーバーを保つ作りです。

落とし穴

ヘッドレスの権限確認で止まる

公式の例は、使うツールを3つのmcp__stagehand__ツールだけに絞り、それ以外はcanUseToolで拒否しています。ヘッドレス実行では、応答のない権限確認に当たると止まるためです。claude -pでも--allowedToolsで事前に許可しておきます。

落とし穴

ANTHROPIC_API_KEYがMCPの子プロセスに渡らない

Agent SDKの例では、ANTHROPIC_API_KEYはMCPの子プロセスへ転送されません。子プロセスが受け取るのはStagehandとBrowserbaseの設定、Nodeの起動に要る値だけです。Stagehand側でモデルを使うなら、STAGEHAND_MODEL_API_KEYを別に渡します。

ほかのブラウザ操作との選び方

Claude Codeのブラウザ操作は、実行場所と、ツールがやってくれる範囲で選びます。

方法ブラウザの場所向く場面
Stagehandのstdioアダプター(本稿)ブラウザの場所ローカルのChromeまたはBrowserbase向く場面1つのブラウザセッションを使い続け、ログイン後の操作もまとめて任せたい
Browserbase MCPサーバーブラウザの場所Browserbaseのクラウド向く場面ビルドなしで、URLとAPIキーだけで始めたい
Playwright MCPブラウザの場所手元で起動するブラウザ向く場面画面構造を使ったE2Eテストをしたい
Chrome DevTools MCPブラウザの場所手元のChrome向く場面開発中のページを計測・デバッグしたい

Stagehandのアダプターは実験的で、リポジトリのビルドが前提です。気軽に試すだけなら、ビルド不要のホスト型が先です。

まとめ

Stagehandは、リポジトリをビルドしてstdio-server.mjsをMCPサーバーとして登録すれば、Claude Codeからブラウザを使えます。プラグインとして入れる形ではありません。

入れる前に決めておくのは2点です。ブラウザをローカルのChromeに置くかBrowserbaseに置くかと、任意のJavaScriptを実行するrunをどの権限で通すかです。ログイン済みの重要なセッションをつなぐ場合は、runを毎回確認にしておくと安心です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →