Microsoft Playwright MCP: The Official Server & GitHub Repo Explained

Search npm or GitHub for "Playwright MCP" and you'll find several packages that look alike. Only one of them is built by the people who build Playwright. That's Microsoft Playwright MCP, and if you're putting an AI agent anywhere near your test suite, it's the one you should know well.

This guide is a tour of the official server and its Playwright MCP GitHub repository: who maintains it, what's in the README, how the tools are grouped, which capabilities are opt-in, how to configure it with JSON, and how to keep it up to date. If you're new to the concept, start with What Is the Playwright MCP Server?. If you just want it installed, the Playwright MCP Server setup guide covers every client step by step.

What Is Microsoft Playwright MCP?

Microsoft Playwright MCP is a Model Context Protocol (MCP) server that gives large language models browser automation through Playwright. The repo's own one-line description: it "enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models."

In practice, your AI client (VS Code with Copilot, Claude Code, Cursor and so on) starts the server, the server launches a real Chromium, Firefox, WebKit, Chrome or Edge browser, and the model calls tools like browser_navigate, browser_snapshot and browser_click to work with the page. The README lists three key features:

• Fast and lightweight — it uses Playwright's accessibility tree, not pixel-based input.
• LLM-friendly — no vision model is needed; the model works on structured data.
• Deterministic tool application — element references from the snapshot avoid the guesswork of clicking on screenshot coordinates.

That snapshot-first design is the main reason the official server feels more reliable than screenshot-driven browser agents. The model clicks a known element reference, not a guessed pixel.

Inside the Playwright MCP GitHub Repo (microsoft/playwright-mcp)

The Playwright MCP GitHub repository lives at github.com/microsoft/playwright-mcp under the official Microsoft organization. Here's what's in it and what each part is for.

As of October 2026 the repo has roughly 37.8k GitHub stars and 3.2k forks, which makes it one of the most widely adopted MCP servers around. A large user base also means most problems you hit have already been reported in the repo's Issues.

The README's own advice: MCP vs Playwright CLI

The first thing the README does is point some readers elsewhere. If you use a coding agent, Microsoft suggests the companion Playwright CLI with SKILLs, because CLI calls are more token-efficient. They don't load big tool schemas and accessibility trees into the context window. MCP, the README says, "remains relevant for specialized agentic loops that benefit from persistent state, rich introspection, and iterative reasoning over page structure, such as exploratory automation, self-healing tests, or long-running autonomous workflows." We compare the two in Playwright CLI vs MCP Server: token cost.

Playwright MCP Tools, Grouped by Capability

The official server organizes its tools into groups. Core automation and tab management are on by default. The rest are opt-in, so the model only sees tool schemas you actually need, which keeps token use down.

Two things to note for QA work. First, browser_snapshot is the workhorse: it returns the accessibility tree with element references the model uses for every later action. Second, the testing capability adds assertion and locator-generation tools, which help when you want the agent to verify behavior and hand back stable locators, not only click around. For how this plays out in real suites, see Playwright MCP for testing and Playwright MCP automation.

Installing @playwright/mcp (the Short Version)

Every client uses the same standard config from the README:

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

Some clients have a one-liner too:

# Claude Code
claude mcp add playwright npx @playwright/mcp@latest

# VS Code (GitHub Copilot agent mode)
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

That's the whole install. For Claude Desktop, Cursor, Windows path quirks, and verifying the connection, follow the full setup guide. If you're specifically on Claude Code, Playwright MCP Server with Claude Code goes further.

Supported Clients

Because it speaks standard MCP, the official server works with any MCP client. The README has dedicated install instructions for:

• VS Code / VS Code Insiders with GitHub Copilot agent mode, plus the Copilot CLI (see our Playwright + GitHub Copilot guide)
• Claude Code and Claude Desktop
• Cursor and Windsurf (comparison: Playwright MCP vs Cursor Agent)
• Cline, Codex, Gemini CLI, Goose, Junie, Kiro, LM Studio, opencode, Qodo Gen, Warp, Amp, Antigravity, Factory and Grok

Key Configuration Options (with JSON)

The server takes dozens of CLI flags, and each one has a matching PLAYWRIGHT_MCP_* environment variable. These are the ones QA engineers reach for most:

Here's a QA-friendly setup: isolated sessions, a saved login, the testing capability, and headless Chromium:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--isolated",
        "--storage-state=./auth/storage.json",
        "--caps=testing",
        "--headless"
      ]
    }
  }
}

For larger setups, move the settings into a config file and pass --config path/to/config.json. The file follows the schema in the README:

{
  "browser": {
    "browserName": "chromium",
    "isolated": true,
    "launchOptions": { "headless": true },
    "contextOptions": { "viewport": { "width": 1280, "height": 720 } }
  },
  "capabilities": ["testing", "devtools"],
  "testIdAttribute": "data-test",
  "outputDir": "./mcp-output",
  "timeouts": { "action": 5000, "navigation": 60000 }
}

Profiles: persistent, isolated, or extension

By default the server uses a persistent profile (stored under ms-playwright/mcp-{channel}-{workspace-hash} in your OS cache folder), so logins survive between sessions. Only one browser can use a persistent profile at a time, so the README recommends --isolated or a separate --user-data-dir when you run several clients in parallel. The third option is the browser extension, which connects to tabs in your existing Chrome or Edge with your real logged-in state. For login-heavy apps, read Playwright MCP authentication.

Official vs Community Playwright MCP Servers

"Playwright MCP" isn't a trademarked product name, and several projects use it. The best known community alternative is @executeautomation/playwright-mcp-server from the ExecuteAutomation GitHub organization (repo: executeautomation/mcp-playwright). It's a legitimate open-source project, but it's not the Microsoft one.

Why prefer the official server? Three reasons:

1. It tracks Playwright itself. The same team ships the browsers, the accessibility snapshot format and the MCP server, so new Playwright features show up quickly.
2. Docs and tutorials line up. The official README's install commands and one-click buttons for VS Code, Cursor, Claude and the rest all use @playwright/mcp, and most tutorials follow them. Mixing packages is a common cause of the "tool not found" problems in our Playwright MCP errors fix guide.
3. Supply-chain trust. An npm package under the @playwright scope, published by Microsoft, is an easier sell to a security review than a lookalike name.

Staying Updated and Pinning Versions

The package is still on 0.0.x versions, and releases come often. That's great for features and risky for a stable test pipeline. Here's the workflow I recommend:

• Local exploration: keep @playwright/mcp@latest so you always get fixes.
• Team configs and CI: pin an exact version, e.g. "args": ["@playwright/mcp@0.0.83"], and bump it on purpose.
• Check versions: npm view @playwright/mcp version shows the newest published release.
• Read before upgrading: watch the repo's Releases (GitHub → Watch → Custom → Releases) and skim the notes for renamed tools or changed defaults.
• Report issues upstream: search the repo's Issues before filing, and include your client, OS, browser and the exact package version.

For the bigger picture of what changed in Playwright this year, see Playwright: what's new in 2026.

How It Relates to Playwright Test Agents

Playwright now ships its own Test Agents: a planner, a generator and a healer. You add them with npx playwright init-agents --loop=vscode (or --loop=claude, --loop=codex, --loop=opencode). The Playwright docs describe agent definitions as "collections of instructions and MCP tools," so the agents run on the same tool-calling model that Playwright MCP made popular.

The difference is scope. Playwright MCP is a general-purpose browser for any AI client: explore a site, reproduce a bug, fill a form, check a page. Test Agents are opinionated workflows built into @playwright/test for planning, writing and fixing tests in your repo. Many teams use both: MCP for ad-hoc exploration and Test Agents for the test suite. Our Playwright MCP Server tutorial shows the exploration side end to end.

Frequently Asked Questions

Meet Your Instructor

Asim Noaman

Senior QA Automation Engineer & AI Testing Specialist

With years of hands-on experience building test automation frameworks for production applications, Asim specializes in combining traditional QA methodologies with cutting-edge AI tools. He has helped teams adopt Playwright and AI-driven testing workflows to ship faster with fewer bugs.

Udemy Instructor Published course author

Playwright + AI Expert Specialized in AI-powered QA

Production Experience Enterprise-grade frameworks

Connect on LinkedIn