--- title: "How to Set Up Playwright MCP in Claude Code, Cursor, Codex and VS Code" description: "Install Microsoft's Playwright MCP server in Claude Code, Cursor, Codex and VS Code, with useful options, example prompts and troubleshooting." canonical: "https://momentic.ai/blog/playwright-mcp-setup" last-updated: "2026-10-31T02:14:40Z" --- # How to Set Up Playwright MCP in Claude Code, Cursor, Codex and VS Code URL: https://momentic.ai/blog/playwright-mcp-setup [blog](/blog) [/ resources](/blog/category/resources) / playwright-mcp-setup Resources Install the Playwright MCP server in Claude Code, Cursor, Codex and VS Code, pick the options that matter, and fix the errors you are likely to hit. Wei-Wei Wu CEO, Momentic ## What Playwright MCP is Playwright MCP gives a coding agent browser access through the [Microsoft Playwright MCP server](https://github.com/microsoft/playwright-mcp). The agent can open a page, inspect it, and interact with elements while you work in Claude Code, Cursor, or another MCP client. The server exposes browser tools for actions such as navigation, clicking, typing, and taking screenshots. For page inspection, it can return an accessibility snapshot that identifies elements by roles and accessible names. An agent can use that structure to find a button or form field without interpreting a screenshot. The browser session helps the agent check what a page currently does, but it does not create a saved Playwright test. ## Prerequisites Playwright MCP needs Node.js 18 or newer and a supported browser (Chrome, Firefox, WebKit or Edge) on the machine that runs the server. The [project README](https://github.com/microsoft/playwright-mcp) lists browser installation steps. Check the environment where your coding agent launches MCP servers, not just your usual terminal. A locally installed browser will not help if the server runs in a container or remote development environment that cannot access it. ## Install and configure by client Each client needs a configuration that starts the [Playwright MCP server](https://github.com/microsoft/playwright-mcp) with `npx`. Use the configuration format for your coding agent below. ### Claude Code Add the server with Claude Code’s MCP command. `claude mcp add playwright npx @playwright/mcp@latest` ### Cursor In Cursor, open **Cursor Settings** > **MCP** > **Add new MCP Server**, pick the `command` type and enter `npx @playwright/mcp@latest`. To share the config with your team, commit it as `.cursor/mcp.json` in the project instead: `{ "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] } } }` ### Codex Add the server with the Codex CLI: `codex mcp add playwright npx "@playwright/mcp@latest"` Or add the entry to `~/.codex/config.toml` yourself: `[mcp_servers.playwright] command = "npx" args = ["@playwright/mcp@latest"]` ### VS Code and GitHub Copilot Register the server with VS Code so GitHub Copilot can access its browser tools. `code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'` ## Useful options Playwright MCP lets you choose how the browser runs. The [server README](https://github.com/microsoft/playwright-mcp) documents `--headless` for runs without a visible browser window, `--browser` for choosing a browser, and `--isolated` for a profile that stays in memory rather than being saved to disk. `npx @playwright/mcp@latest --headless --browser=firefox --isolated` Use `--isolated` when you do not want a session to reuse saved cookies or logins. A persistent profile can only be used by one browser at a time, so if you run several agents at once, start each extra one with `--isolated` or its own `--user-data-dir`. Leave it off when you need a persistent profile, such as one you have already signed into. Add the same flags to the server command in your client configuration if you want them to apply whenever your coding agent starts Playwright MCP. ## Five example prompts Replace the URLs and UI labels with ones from your application. Each prompt asks the coding agent to report what it observed rather than assume an interaction succeeded. 1. **Check navigation.** “Open http://localhost:3000. Click the Pricing link and report the final URL and page heading.” The agent follows the link and checks whether the destination matches its label. 2. **Inspect form validation.** “Open http://localhost:3000/signup. Submit the form without entering any values. List the validation messages you can see, and do not create an account.” The agent tests the empty-form state without supplying credentials. 3. **Verify a code change.** “Open http://localhost:3000/settings. Check whether the Save button becomes enabled after I change a field. Do not click Save.” The agent checks the behavior affected by your change without modifying stored settings. 4. **Check a narrow viewport.** “Open http://localhost:3000 at a 375-pixel viewport width. Check whether the main navigation is accessible and report any controls you cannot reach.” The agent resizes the browser and tests navigation rather than judging appearance alone. 5. **Inspect a failed request.** “Open http://localhost:3000/products. If the product list fails to load, report the visible error and any relevant browser console messages.” The agent gathers evidence you can use to investigate the failure. ## Troubleshooting ### Browser fails to launch If the agent reports a missing browser executable, check which browser you selected in the Playwright MCP configuration. Install that browser using the instructions in the [project README](https://github.com/microsoft/playwright-mcp), then restart the MCP server. A successful server startup does not confirm that the selected browser can launch. ### Permission or port errors If the browser cannot start, check whether the process can write to its configured profile directory. An isolated profile still needs a writable location. If you configured a network port, check whether another process already uses it. A port conflict does not apply to configurations that communicate with the server through standard input and output. ### Slow or oversized browser output If an accessibility snapshot takes too long or floods the agent’s context, ask the agent to search the page with the `browser_find` tool or pass a `depth` limit to `browser_snapshot` instead of capturing the whole page again. Close tabs the task no longer needs, and avoid taking another snapshot when the previous one already contains the element the agent needs. ## What Playwright MCP doesn't do [Playwright MCP](https://github.com/microsoft/playwright-mcp) lets a coding agent drive a browser during a session. The server does not save that session as a test, rerun it after a later commit, or gate a deploy in CI. An agent could write a Playwright test using its other tools, but browser access alone does not create a maintained test suite. If you need the agent to work with tests that run beyond the current session, [Momentic’s MCP server](https://momentic.ai/docs/coding-agents/mcp-server) connects it to a testing system. The [comparison of browser and testing MCP servers](https://momentic.ai/blog/playwright-mcp-vs-testing-mcp-server) explains where each fits. ## Frequently asked questions Is Playwright MCP free? Yes. Microsoft publishes Playwright MCP as an open-source server. You can run the server locally without paying for a Playwright MCP subscription. Your coding agent or any hosted services you use may have separate costs. How does Playwright MCP differ from Playwright Test? Playwright MCP lets a coding agent drive a browser and inspect the page during a session. Playwright Test runs test files with assertions that you can commit and run again in CI. An agent's browser session does not create a saved test suite or a CI gate. Does Playwright MCP work with Firefox and WebKit? Yes. The server supports both through its --browser option. Use --browser firefox or --browser webkit, and make sure the selected browser is installed before starting the server. Still have additional questions? ## Keep reading. [Resources Testing iOS and Android apps with Claude Code Four ways to test iOS and Android apps with Claude Code, from simctl and adb to XCUITest, Espresso, mobile MCP servers and Momentic mobile tests. Wei-Wei Wu 12 min read](/blog/claude-code-mobile-app-testing)[Resources UI and end-to-end testing with OpenAI Codex How far Codex gets on UI and end-to-end tests, and how AGENTS.md instructions plus a test runner over MCP turn its output into checks you can trust. Wei-Wei Wu 8 min read](/blog/codex-ui-testing-guide)[Resources Migrating from Appium to Maestro How to move an Appium suite to Maestro flows, with a worked login example, a concept map and the cases where Appium is still the better fit. Wei-Wei Wu 6 min read](/blog/migrate-appium-to-maestro) ## Close the feedback loop. Point Momentic at your app. Free to start, no credit card. [Try for free](https://app.momentic.ai/signup) [Contact sales](/sales)