TL;DR: Playwright MCP is an MCP server that hands an AI agent a real browser it can drive, so a model can navigate, click, fill forms, and read pages instead of only reading text. Running it locally gives you a browser on your own machine, which is ideal for development. To run the same tools against a browser that lives anywhere and survives bot checks, point your agent at a hosted browser MCP server over Streamable HTTP. This guide covers both, with runnable config for each.

Most agents can read the web but cannot use it. They fetch a page, summarize the HTML, and stop the moment a task needs a login, a button click, or data behind a form. Playwright MCP closes that gap by giving the model a browser as a set of tools it can call over one open protocol.

What is Playwright MCP?

Playwright MCP is a server that exposes browser control to an AI model through the Model Context Protocol (MCP), the open standard Anthropic introduced in November 2024 for connecting models to tools and data. The server advertises a set of browser tools, and any MCP-aware client can call them. The model decides what to do, and the server does it in a browser.

If you are new to MCP itself, start with what an MCP server is, then come back here for the browser-specific setup.

Local browser or cloud browser?

You can run a browser MCP server two ways, and the choice comes down to where the browser runs and what it has to withstand. A local server drives a browser on your own machine. A hosted server drives a browser in the cloud that any of your agents can reach.

What do you need before you start?

You need an MCP client (Claude Code, Cursor, Claude Desktop, or any client that speaks MCP) and, for the cloud path, a Browserbase API key from the dashboard. No other infrastructure is required for the hosted server.

How do you run Playwright MCP against a cloud browser?

The fastest path to a cloud browser is the hosted Browserbase MCP server. It runs on Browserbase infrastructure and exposes browser tools over Streamable HTTP, so your client connects to a URL instead of managing a browser process. Add one server entry to your MCP client config.

{
  "mcpServers": {
    "browserbase": {
      "url": "https://mcp.browserbase.com/mcp?browserbaseApiKey=YOUR_BROWSERBASE_API_KEY"
    }
  }
}

Claude Code users can add the same server with one command.

claude mcp add --transport http browserbase "https://mcp.browserbase.com/mcp?browserbaseApiKey=YOUR_BROWSERBASE_API_KEY"

Restart your client, then ask it to do something on the web, for example Navigate to example.com and extract the main heading. The browser runs in the cloud, and you can watch the live session in the Browserbase dashboard.

How do you reach sites that challenge automated traffic?

Some sites check whether a visitor looks like a real user before they serve content. The hosted server takes query parameters that turn on managed proxies and Verified access, so the browser presents as a trusted visitor. Set proxies and verified to the exact string "true".

{
  "mcpServers": {
    "browserbase": {
      "url": "https://mcp.browserbase.com/mcp?browserbaseApiKey=YOUR_BROWSERBASE_API_KEY&proxies=true&verified=true"
    }
  }
}

Verified is how Browserbase works with bot-protection providers to give agents verified access to protected sites. It is available on the Scale plan. The boolean query values must be the exact strings "true" or "false", not unquoted booleans.

How do you run Playwright MCP locally?

For development, run the server locally over STDIO with the npm package. Your client launches the process and talks to it on standard input and output. Add this to your MCP client config and set your keys in the environment block.

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "your_api_key",
        "GEMINI_API_KEY": "your_gemini_api_key"
      }
    }
  }
}

This still drives a cloud browser under the hood, but your client runs the server process. Reach for it when you want to develop against the server on your own machine before moving to the hosted endpoint.

How do you drive the same browser from Playwright directly?

MCP is for letting a model decide the actions. When you want deterministic scripted control instead, connect the Playwright SDK to the same kind of cloud browser over the Chrome DevTools Protocol. Create a session, then connect Playwright to its CDP endpoint.

import { chromium } from "playwright-core";
import Browserbase from "@browserbasehq/sdk";

const bb = new Browserbase({
  apiKey: process.env.BROWSERBASE_API_KEY,
});

(async () => {
  const session = await bb.sessions.create();
  console.log(`Session created, id: ${session.id}`);

  const browser = await chromium.connectOverCDP(session.connectUrl);
  const defaultContext = browser.contexts()[0];
  const page = defaultContext.pages()[0];

  await page.goto("https://www.browserbase.com/", {
    waitUntil: "domcontentloaded",
  });

  await page.screenshot({ fullPage: true });
  await page.close();
  await browser.close();
})();

The same account, the same cloud browser, two ways to drive it. Let the model call MCP tools when the task is open-ended, and script Playwright directly when the steps are fixed.

Common errors

• No active session: Some clients open a new transport on every tool call, so the server has no active session to fall back on. Pass the sessionId returned by the start tool on each later call to target the right browser.
• Boolean parameter ignored: Query values like proxies and verified must be the exact strings "true" or "false". An unquoted true is dropped.
• Model key missing: A non-default model needs its own API key. Pass modelName together with modelApiKey, or leave both unset to use the default.

How do you take it to production?

A local server is fine while you build. In production the browser has to run somewhere reliable, reach sites that guard against automated visitors, and be observable when a run goes wrong. The hosted browser MCP server runs on the same infrastructure that handles more than 35 million browser sessions a month, with managed proxies, Verified access, and session recording built in. Point your agents at the hosted endpoint and you get all of that behind one URL.

Last updated: August 17, 2026