How to Set the Default Browser in Playwright MCP

Set the browser on the Playwright MCP server. Add --browser=<name> to the server’s args array. For example, this configuration starts Playwright MCP with Firefox:

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

The supported CLI values are chrome, firefox, webkit, and msedge. Chrome is the default. Playwright’s official setup guide describes this as choosing a browser; the setting belongs to the MCP server configuration, while the surrounding file format depends on your MCP client. See the official getting-started guide and the Playwright MCP repository.

1. Configure the browser in your MCP client

Find the MCP server configuration used by Claude Desktop, Cursor, or another MCP client. Keep the browser flag in the Playwright server’s argument list:

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

Replace chrome with firefox, webkit, or msedge. Restart the MCP client after changing the configuration so it starts a new server process with the new argument.

Supported browser values

CLI value	Browser selected	Use it when
`chrome`	Google Chrome	You need the default Chromium-based desktop browser.
`firefox`	Firefox	You need Firefox-specific rendering or compatibility checks.
`webkit`	WebKit	You need WebKit coverage, such as Safari-like behavior.
`msedge`	Microsoft Edge	You need to automate the Edge channel.

Browser choice changes the engine or channel. It does not choose headless mode, profile persistence, or whether Playwright connects to an already-running browser.

2. Choose headed or headless mode separately

Playwright MCP runs headed by default. Add --headless when the server must run without a visible browser window:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--browser=firefox",
        "--headless"
      ]
    }
  }
}

A browser can be selected correctly while still failing to start if the machine has no display. In IDE workers, containers, and CI, use --headless, or run the MCP server separately over HTTP when headed operation is required on a host with a display. The official guide covers this separate-server arrangement.

3. Set the browser with an environment variable

The Playwright MCP README documents PLAYWRIGHT_MCP_BROWSER for process-level configuration:

export PLAYWRIGHT_MCP_BROWSER=firefox
npx @playwright/mcp@latest

This is useful when the same MCP configuration is deployed to several environments and each environment supplies its own browser. Keep the value aligned with the supported browser names for the server you are running.

4. Use a reusable JSON configuration file

For advanced settings, start the server with --config and set the browser in the configuration file:

{
  "browser": {
    "browserName": "firefox"
  }
}

npx @playwright/mcp@latest --config path/to/config.json

The configuration schema uses chromium, firefox, or webkit for browser.browserName. This field is different from the CLI’s browser or channel names: the CLI documents chrome, firefox, webkit, and msedge.

Configuration precedence

When the same setting is supplied in more than one place, Playwright MCP applies settings in this order:

Configuration file
Environment variables
Command-line arguments

The later source wins. Therefore, an explicit --browser=... argument overrides the environment and JSON configuration values.

5. Keep browser state independent from browser selection

Changing the browser does not automatically change the profile or login state.

Persistent profile: the default mode preserves cookies and logins between runs.
Isolated session: add --isolated for a fresh session.
Storage state: use --storage-state to load cookies and local storage into an isolated session.
Profile directory: use --user-data-dir to select a specific profile directory.

npx @playwright/mcp@latest \
  --browser=chrome \
  --isolated \
  --storage-state=./state.json

Use an isolated session for repeatable tests and a persistent profile when the MCP agent must retain a login. Treat storage-state files and profile directories as credentials because they can contain active cookies.

6. Connect to an existing browser instead of launching one

If the goal is to control a browser that is already open, use a documented connection method rather than assuming --browser will attach to it. Playwright MCP documents browser channels, CDP endpoints, Playwright server endpoints, and a browser extension. The extension can reuse existing tabs, cookies, installed extensions, and logged-in sessions; --profile-dir-name selects the profile used by the extension.

This approach is useful when an agent must work inside a manually prepared session or when the required extension is already installed. It also avoids confusing “which browser to launch” with “which running browser to control.”

7. Verify the effective configuration

Stop the existing MCP server process.
Check the final server entry, including args, environment variables, and --config.
Remove conflicting browser settings while diagnosing.
Start the client again and ask the agent to open a page.
Confirm the browser window or user agent matches the selected engine.

If the result is unexpected, remember that command-line arguments override environment and file settings. Also check whether the client is launching a different MCP server entry than the one you edited.

8. Common errors and fixes

Error or symptom	Likely cause	Fix
The browser remains Chrome	A higher-precedence argument still sets Chrome, or the client did not restart.	Inspect the complete `args` array, remove conflicting values, and restart the MCP client.
Unknown browser value	A config-file name was used in the CLI, or the value is misspelled.	Use CLI names such as `chrome` or `msedge`; use `chromium` only for the JSON `browserName` field.
Headed launch fails on a server	No display is available.	Add `--headless`, or run the server separately on a machine with a display and connect over HTTP.
Login disappears after switching modes	`--isolated` starts a fresh context.	Use persistent profile mode or provide `--storage-state`.
Existing tabs are not visible	The server launched a new browser instead of attaching to the running one.	Use the documented extension, CDP, or Playwright endpoint connection method.
Configuration file is ignored	`--config` points to the wrong path or a CLI argument overrides it.	Use an absolute or verified path and remove duplicate command-line settings while debugging.
Firefox or WebKit does not start	The required Playwright browser binary is not installed in the environment.	Install the browser through the Playwright setup process used by your deployment, then restart the server.

9. Performance, reliability, and cost considerations

Startup: launching a new browser and profile adds startup work. A persistent server process avoids repeated launches.
Isolation: isolated sessions improve repeatability but require you to provide authentication state when a site needs login.
Rendering differences: test the browser engine that matches your users. A page that works in Chromium can expose different behavior in Firefox or WebKit.
Headless operation: headless mode is usually the practical choice for CI and remote workers, provided the site does not depend on visible-window behavior.
Reliability: pin the MCP package version in controlled deployments instead of relying indefinitely on @latest, and recheck the official documentation when upgrading.
Cost: Playwright MCP itself does not define a screenshot API billing model. Your costs come from the machines, browsers, network, and any external services used by the workflow.

10. Or skip the browser setup

If your goal is a reliable website screenshot rather than interactive browser control, ScreenshotNeo provides a single HTTP request. It accepts the cookie or consent banner like a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets, and bills only clean shots. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing; each response identifies the result with X-Page-Verdict and X-Billed headers. See the ScreenshotNeo API documentation for all options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://playwright.dev -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://playwright.dev"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://playwright.dev' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. Features include full-page and element capture, dark mode, device presets, retina scale, PDF options, custom CSS and JavaScript, clicks, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, caching, signed links, async webhooks, bulk capture, usage reporting, and an OpenAPI specification.

There is a free tier of 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.

FAQ

What is the default browser?

Google Chrome is the default browser for Playwright MCP.

Can I select Safari?

Use --browser=webkit for WebKit-based coverage. The CLI does not use safari as the browser value.

Does `--browser` make the server headless?

No. Browser selection and display mode are separate. Add --headless when needed.

Why does the JSON config say `chromium` while the CLI says `chrome`?

They are names from different configuration interfaces. Use chromium in browser.browserName; use chrome in the CLI argument.

Use persistent profile mode, load storage state, or connect through the documented extension or endpoint method to an already-running browser.