Skip to content
MCP Shelf

Pod to App: Codex

How to install the Playwright MCP server in Codex

By Sophie Filer · Updated 11 Nov 2026 · Steps checked against Playwright's own docs on 11 Nov 2026

The short answer

Run codex mcp add playwright npx "@playwright/mcp@latest". Codex saves it in ~/.codex/config.toml, starts the server whenever it needs a browser, and you can check it with /mcp.

Terminal
codex mcp add playwright npx "@playwright/mcp@latest"
Needs
Node.js 18 or newer
Config file
~/.codex/config.toml
Sign-in
None
Price
Free, Apache 2.0

Install it step by step

  1. Step 1: Check Node.js with node --version; you need 18 or later because the server runs through npx.
  2. Step 2: Run the command at the top of this page. The quotes around the package name stop some shells from treating @ specially.
  3. Step 3: Start Codex and type /mcp. playwright should show with tools such as browser_navigate, browser_snapshot and browser_click.
  4. Step 4: Give it a real job: "Start the dev server, open the sign-up page, submit the form empty and tell me which errors appear."

Or write the config by hand

~/.codex/config.toml
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

The Codex CLI and the Codex IDE extension both read this file, so one entry gives you Playwright in either.

Useful flags for Codex

Add flags to the args list. These are the ones that matter most when Codex is driving:

~/.codex/config.toml
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest", "--headless", "--isolated", "--output-dir", "./playwright-output"]
FlagWhy you might want it
--headlessCodex often runs in a terminal or over SSH with no screen to show a window
--isolatedA clean, in-memory profile each time, so old cookies do not change test results
--output-dirWhere screenshots and other files land, instead of a temporary folder
--browser firefoxCheck another engine; Chrome, Edge and WebKit work too
--caps visionAdds clicking by screen position, for canvas-heavy pages

When the browser cannot open where Codex runs

On a remote box or in a container there is often no screen, so a normal browser window fails to start. Either keep --headless in the args, or start the server yourself on a machine that can run a browser and point Codex at it by URL:

Terminal, then ~/.codex/config.toml
npx @playwright/mcp@latest --port 8931

[mcp_servers.playwright]
url = "http://localhost:8931/mcp"

If it does not work

What you seeWhat to do
playwright missing from /mcpRun codex mcp list to see what was saved, and check the table name is [mcp_servers.playwright].
Server fails to startNode.js is missing or too old for npx. Install 18 or later and restart Codex.
Browser will not launchNo display is available. Add --headless, or use the standalone server.
Codex takes a long time per stepPage snapshots are large. Ask for one page or one flow at a time.

MCP Shelf take

Is Playwright worth adding to Codex?

Codex with Playwright MCP can check its own front-end work: change the component, load the page, click through, read what broke. That alone makes it worth the one command. Two cautions. Snapshots are token-heavy, so long browsing sessions get slow and costly. And Microsoft now suggests the Playwright CLI with skills for coding agents when efficiency matters. Our advice: use the MCP server to explore and reproduce bugs, then have Codex write proper Playwright tests you can run in CI.

Sophie Filer

Questions

Does Playwright MCP work in the Codex IDE extension too?

Yes. The extension and the CLI share ~/.codex/config.toml, so once the server is added it is available in both.

Can Codex see screenshots from Playwright?

Codex can take screenshots with browser_take_screenshot, but it mainly works from accessibility snapshots, which describe the page as text. Screenshots are saved to the output directory if you set one.

How do I remove Playwright MCP from Codex?

Delete the [mcp_servers.playwright] table from ~/.codex/config.toml, or use codex mcp remove playwright, then restart Codex.

Sources: the steps on this page are written in our own words from Playwright MCP's own install docs, the README. If they disagree with this page, the project's docs win; please tell us from the server page.