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.
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
- Step 1: Check Node.js with
node --version; you need 18 or later because the server runs throughnpx. - Step 2: Run the command at the top of this page. The quotes around the package name stop some shells from treating
@specially. - Step 3: Start Codex and type
/mcp. playwright should show with tools such asbrowser_navigate,browser_snapshotandbrowser_click. - 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
[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:
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest", "--headless", "--isolated", "--output-dir", "./playwright-output"]| Flag | Why you might want it |
|---|---|
--headless | Codex often runs in a terminal or over SSH with no screen to show a window |
--isolated | A clean, in-memory profile each time, so old cookies do not change test results |
--output-dir | Where screenshots and other files land, instead of a temporary folder |
--browser firefox | Check another engine; Chrome, Edge and WebKit work too |
--caps vision | Adds 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:
npx @playwright/mcp@latest --port 8931
[mcp_servers.playwright]
url = "http://localhost:8931/mcp"If it does not work
| What you see | What to do |
|---|---|
playwright missing from /mcp | Run codex mcp list to see what was saved, and check the table name is [mcp_servers.playwright]. |
| Server fails to start | Node.js is missing or too old for npx. Install 18 or later and restart Codex. |
| Browser will not launch | No display is available. Add --headless, or use the standalone server. |
| Codex takes a long time per step | Page 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.