mcp-agent-playwright

Playwright browser automation for AI agents, as a local MCP server. Navigate, read accessibility snapshots, click, type, screenshot, and evaluate JavaScript in a real browser.

Build to be called by any MCP-aware agent harness (opencode, Claude, LM Studio agents, etc.) over stdio. Works in two modes:

• Own browser (default) — lazily launches a fresh Playwright browser on first use and keeps it alive between tool calls.

• CDP attach — set MCP_PLAYWRIGHT_CDP_ENDPOINT to connect over Chrome DevTools Protocol to an already-running browser (Brave, Chrome, …). The server adopts the existing tabs and detaches on close — it never shuts the user's browser down.

Tool surface

Related MCP server: agentic-browser-mcp

Requirements

• Python 3.11+

• uv

Install

git clone <repo-url> mcp_agent_playwright
cd mcp_agent_playwright
uv sync

Install a Playwright browser binary:

uv run playwright install chromium

Usage

Run as an MCP server (stdio — what harnesses expect)

uv run mcp-agent-playwright

Register in an MCP client

{
  "mcpServers": {
    "playwright": {
      "command": "uv",
      "args": ["--project", "/path/to/mcp_agent_playwright", "run", "mcp-agent-playwright"]
    }
  }
}

Attach to a running browser (CDP mode)

Launch your browser with the debugging flag (example: Brave):

Start-Process -FilePath "C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe" `
  -ArgumentList '--remote-debugging-port=9222','--remote-allow-origins=*'

Replace the -FilePath with your browser's actual path (Brave, Chrome, Edge, or any Chromium-based browser).

Then set MCP_PLAYWRIGHT_CDP_ENDPOINT when starting the server (or in the MCP client config):

{
  "mcpServers": {
    "playwright": {
      "command": "uv",
      "args": ["--project", "/path/to/mcp_agent_playwright", "run", "mcp-agent-playwright"],
      "env": { "MCP_PLAYWRIGHT_CDP_ENDPOINT": "http://127.0.0.1:9222" }
    }
  }
}

browser_status reports which mode is active (mode: cdp vs mode: own-browser). If the CDP endpoint is configured but unreachable, the server falls back to launching its own browser and says so in the status note.

Workflow

Start with browser_navigate(url), then browser_snapshot to see the page as a numbered accessibility tree. Interact using a [ref] number or a locator string (role=button,name=Submit, css=#id, text=Hello). Always snapshot again after actions.

Configuration reference

Development

uv run ruff check .     # lint
uv run pyright          # type check (src + tests, against .venv)
uv run pytest -q        # tests

uv sync installs the dev tooling (pytest, pytest-asyncio, pyright, ruff). The suite has two tiers: plain unit tests that need no browser, and tests marked browser that drive a real headless Chromium. The browser tier needs uv run playwright install chromium once; until then those tests skip rather than fail. CI installs Chromium, so nothing skips there.

License

MIT © 2026 Christof Milius