What's going on?
Motivation
Coding agents driving the Playwright MCP server can only test a UI in whatever color scheme
the browser happened to start in. Frontend work almost always needs both — an agent that
implements or reviews a dark theme currently has no way to see it.
Nothing on the MCP surface exposes the color scheme today:
- None of the ~70 tools touches it (
browser_resize is the closest neighbour).
- There is no CLI flag and no
PLAYWRIGHT_MCP_* env var for it.
The existing workarounds are all unsuitable for an agent mid-session:
browser.contextOptions.colorScheme in the JSON config file — requires writing a config
file and restarting the server, and is fixed for the whole session.
--init-page calling page.emulateMedia({ colorScheme: 'dark' }) — same restart problem.
browser_run_code_unsafe — arbitrary code execution, off by default for good reason, and
not something an agent should reach for to flip a media query.
Playwright itself supports this fully via
page.emulateMedia() and
contextOptions.colorScheme, so this is purely about surfacing existing capability.
Proposal
1. A browser_emulate_media tool wrapping page.emulateMedia(), with all parameters
optional so omitted media features are left unchanged:
| Parameter |
Values |
colorScheme |
light, dark |
reducedMotion |
reduce, no-preference |
forcedColors |
active, none |
contrast |
more, no-preference |
media |
screen, print |
Scope matches browser_resize: core capability (available by default), applies to the
current page only, since page.setViewportSize() is per-page in exactly the same way.
Mirroring emulateMedia rather than adding a color-scheme-only tool means reduced-motion,
forced-colors and print emulation come along without a second tool later — useful for
accessibility and print-stylesheet testing.
2. A --color-scheme <light|dark> CLI option (plus PLAYWRIGHT_MCP_COLOR_SCHEME),
mapping to contextOptions.colorScheme alongside the existing --viewport-size and
--user-agent handling, so a whole session can be started in dark mode without a config
file.
Example
browser_navigate { "url": "http://localhost:3000" }
browser_take_screenshot
browser_emulate_media { "colorScheme": "dark" }
browser_take_screenshot
What's going on?
Motivation
Coding agents driving the Playwright MCP server can only test a UI in whatever color scheme
the browser happened to start in. Frontend work almost always needs both — an agent that
implements or reviews a dark theme currently has no way to see it.
Nothing on the MCP surface exposes the color scheme today:
browser_resizeis the closest neighbour).PLAYWRIGHT_MCP_*env var for it.The existing workarounds are all unsuitable for an agent mid-session:
browser.contextOptions.colorSchemein the JSON config file — requires writing a configfile and restarting the server, and is fixed for the whole session.
--init-pagecallingpage.emulateMedia({ colorScheme: 'dark' })— same restart problem.browser_run_code_unsafe— arbitrary code execution, off by default for good reason, andnot something an agent should reach for to flip a media query.
Playwright itself supports this fully via
page.emulateMedia()andcontextOptions.colorScheme, so this is purely about surfacing existing capability.Proposal
1. A
browser_emulate_mediatool wrappingpage.emulateMedia(), with all parametersoptional so omitted media features are left unchanged:
colorSchemelight,darkreducedMotionreduce,no-preferenceforcedColorsactive,nonecontrastmore,no-preferencemediascreen,printScope matches
browser_resize:corecapability (available by default), applies to thecurrent page only, since
page.setViewportSize()is per-page in exactly the same way.Mirroring
emulateMediarather than adding a color-scheme-only tool means reduced-motion,forced-colors and print emulation come along without a second tool later — useful for
accessibility and print-stylesheet testing.
2. A
--color-scheme <light|dark>CLI option (plusPLAYWRIGHT_MCP_COLOR_SCHEME),mapping to
contextOptions.colorSchemealongside the existing--viewport-sizeand--user-agenthandling, so a whole session can be started in dark mode without a configfile.
Example