🧠

Mastra + Playwright MCPでTypeScript使ってスクリプト書いたら簡単だった

2025/05/10に公開

📘 この記事を読んだら分かること

Mastra と Playwright MCP を使って、LLM でブラウザを自動操作するエージェントを TypeScript で作成する方法
コマンドラインから LLM エージェントを実行する方法
コマンドラインからブラウザを操作できる runPrompt.tsの詳細
プロンプトから Playwright の自動テストステップを作成できるrunTestGen.tsの使い方

コマンドラインのプロンプトから

www.google.comを開いて、宮古島の天気で検索して、サマリーをください

と渡すだけで、ブラウザが操作され、結果が返ってくるスクリプトが作れるようになります。

🎯 この記事の対象者

LLM や MCP を使って Web ページ操作を自動化したいエンジニア
AI エージェントを GUI ではなく CLI で実行できるスクリプトを書いてみたい人
GitHub Actions や CI バッチで AI エージェントを活用したい人

🚀 Mastra とは？

Mastra は、TypeScript で LLM エージェントを簡単に作れる OSS フレームワークです。

現在 Netlify 傘下の Gatsby の元コア開発者が関わるチームによって開発されています。
様々な LLM と MCP ツール（Playwright など）をシンプルなコードで統合し、自然言語の指示で処理を実行できます。
型安全かつ CLI や GitHub Actions でも扱いやすい構成が特徴です。

🌐 Playwright MCP とは？

Playwright MCP (Model Context Protocol) は、LLM などのクライアントから Playwright を使ってブラウザを直接操作できるプロトコルです。

MCP は常駐サーバーとして動作し、HTTP や SSE で命令を受け付けます。
LLM が考えた「クリック」「入力」などの指示をそのまま Playwright がブラウザ上で実行できます。
Mastra との統合により、自然言語から直感的にブラウザを操作するエージェントが作れます。

🧱 サンプルスクリプト

このプロジェクトのサンプルはこちらからダウンロードできます。

ちなみにこのコードの開発を行ったPCは Ubuntu 24.04 です。
NVM 使って Node のバージョンは v22.15.0 にしています。

プロジェクト構成

mastra-playwright-agent/
├── src/
│ ├── runPrompt.ts # プロンプトからブラウザを操作できるスクリプト
│ └── runTestGen.ts # Playwrightのテストステップコードを作成してくれるスクリプト
├── .env # OpenAI API キー
├── package.json
├── tsconfig.json
└── README.md

この最小構成で、LLM と Playwright を使ったブラウザ自動化エージェントをすぐに実行できます。

▶️ `runPrompt.ts` について

runPrompt.ts は、コマンドラインから自然言語プロンプトを入力し、Mastra + Playwright MCP を通じて LLM がブラウザを操作するスクリプトです。

実行方法

.env の中の
OPENAI_API_KEY=sk

を自分の OpenAI の API Key で置き換えてください。

$ npx @playwright/mcp --port 8931

このコマンドは必要ではないんですが、Playwright MCP 実行時にローカルでブラウザが開くのでやってる感が出ます w

$ npx tsx src/runPrompt.ts

このコマンドで実行させると以下が出てきます。

📥 プロンプトを入力してください:>

ここで

www.google.comを開いて、宮古島の天気で検索して、サマリーをください

みたいなプロンプトを入力すると実際にブラウザが開いて操作してサマリーが出てくるのを確認する事ができます。

スクリプトのポイント

const mcp = new MCPClient({
  servers: {
    playwright: {
      url: new URL("http://localhost:8931/sse"),
    },
  },
});

こちらでローカルで走っている Playwrigh MCP を指定して、MCP クライントを作っています。

  playwright: {
    command: "npx",
    args: ["@playwright/mcp@latest"]
  },

playwright の設定はこちらでも動きますが、ローカルのブラウザは立ち上がりません。CI とかで使うときはこちらにした方がいいでしょうね。

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });

const agent = new Agent({
  name: "Browser Agent",
  tools: await mcp.getTools(),
  instructions:
    "あなたはウェブサイトにPlaywrightを使ってアクセスして情報を取得するエージェントです。",
  model: openai("gpt-4o"),
});

ここでAgentにモデルと指示を渡して初期化

async function main() {
  const prompt = await readPrompt();
  try {
    const result = await agent.generate(prompt);
    console.log("✅ 出力:", result.text);
  } catch (error) {
    console.error("❌ エラーが発生しました:", error);
  } finally {
    await mcp.disconnect();
  }
}

main();

agent.generate(prompt) からブラウザが起動して、結果を取得します。

たったこれだけ、簡単でしょ？w

🧪 `runTestGen.ts` について

runTestGen.ts は、プロンプトから Playwright の自動テストステップを作ってくれるスクリプトです。

最初は全部 LLM + Playwright MCP にテストスクリプトも自然言語で入れてテストしようと思ってたんですが、テスト実行時に URL 先のページ全体を LLM が読みに行ってすぐ API のリミットに行くのでテストステップコードは事前に作っておいて必要なときだけ書き換えた方がいいとの結論に達しました。

このスクリプトではPlaywright MCPがwebアプリを操作して取得したDOMデータなどを使って、LLMがPlaywrightのステップコードを生成しています。

npx tsx src/runTestGen.ts

こちらを実行すると以下が表示されます。

📥 プロンプトを入力してください:>

ここで

jp.mercari.com に行って、右上の「ログイン」をクリックして、ログイン画面に遷移するのを確認してください。

と指示すると以下の様な Playwright のステップコードが作成されて /tests 以下に保存されます。

import { test, expect } from "@playwright/test";

test("ログイン画面への遷移を確認", async ({ page }) => {
  await page.goto("https://jp.mercari.com");
  await page.getByRole("button", { name: "ログイン" }).click();
  await expect(page).toHaveURL("https://login.jp.mercari.com/signin");
});

これをどういう風に使いこなすかはみなさんの想像力次第ですが、Gherkin スクリプト管理アプリとから Gherkin のスクリプトが変わった時だけ実行して Playwright のテストステップコードを作ってもらうとかもいいのかなとは思っています。

✅ まとめ

Mastra と Playwright MCP を使えば、自然言語からブラウザ操作を自動化するエージェントが TypeScript で構築できます。
runPrompt.ts は対話実行用、runTestGen.ts は Playwright のテストステップ作成用と使い分けできます。
GUI 不要で、CLI や CI 環境にすぐ導入できるのが大きな利点です。

ぜひ、様々なワークフローやプロンプト設計に合わせてカスタマイズしてみてください。

📎 関連リンク

👨‍💻 著者について

東京とアムステルダムを拠点に活動中。
東欧・南アジアのエンジニアと連携しながら、QA コンサル・テスト自動化・フルスタック開発・PM 業務まで幅広く担当しています。

Cucumber・Playwright・ChatGPT などを活かした効率的なテスト運用や開発基盤づくりのご相談も歓迎です！