How to Use an MCP Server for Headless Browser Automation

To run Playwright MCP headlessly, add the Playwright MCP server to your MCP client configuration and pass --headless in the server arguments:

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

The exact configuration file location depends on the MCP client. Use that client’s MCP setup instructions, then restart or reload the client. Playwright’s official documentation lists Node.js 20 or newer and an MCP client as prerequisites. See the Playwright MCP documentation for the current client examples and options.

What Playwright MCP does

Playwright MCP exposes browser automation through the Model Context Protocol. Microsoft’s documentation describes it this way: “The Playwright MCP server provides browser automation capabilities through the Model Context Protocol, enabling LLMs to interact with web pages using structured accessibility snapshots.”

Instead of giving an AI agent a raw browser debugging interface, the server provides structured page information and browser actions. The agent can navigate, inspect accessible elements, click, type, and continue through a workflow using the tools exposed by the server.

What you need installed

Node.js 20 or newer.
An MCP client that supports server configuration.
Network access for npx to obtain @playwright/mcp@latest, unless your environment already provides the package.
A browser choice that matches your workflow: Chrome, Firefox, WebKit, or Microsoft Edge are documented options.

The research material documents the first two prerequisites directly. Browser installation and client-specific requirements can vary by operating system and MCP client, so check the client and Playwright documentation for your environment.

Configure Playwright MCP for headless mode

1. Find your client’s MCP server configuration

MCP clients do not all store server definitions in the same place. Some use a JSON settings file, while others provide a graphical settings page or project-level configuration. Open the client’s MCP documentation and locate the section for adding a server.

2. Add the server definition

Use this standard Playwright MCP shape:

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

command tells the client to launch npx. The first argument identifies the Playwright MCP package, and --headless starts the browser without a visible window.

3. Restart the MCP client

Most clients read server definitions when they start. Save the configuration, restart the client, and check its MCP or tool status panel. A successful connection should expose Playwright browser tools to the assistant.

Start with a simple request such as navigating to a public page and reporting its heading. This confirms that the client can launch the server, the server can launch a browser, and the agent can read the page before you attempt a multi-step workflow.

How do I run Playwright MCP headlessly?

Headed mode is described as the default in the getting-started guide. Add --headless to the server arguments to disable the visible browser window:

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

Headless mode is useful for remote machines, containers, CI jobs, and desktop environments where no display is available. It changes how the browser is rendered; it does not remove the need to configure the MCP client or provide access to the target site.

Choose a browser engine

Playwright’s documented browser options include Chrome, Firefox, WebKit, and Microsoft Edge. Chrome is the default in the documented options. Select a different engine by adding the corresponding browser option to the server arguments shown in the current Playwright documentation.

Choice	Use it when
Chrome	You want the documented default or your target site is optimized for Chromium.
Firefox	You need to exercise a Firefox-specific workflow.
WebKit	You need WebKit coverage in a browser test matrix.
Microsoft Edge	Your workflow must use Edge.

Do not assume that changing engines produces identical rendering or behavior. If browser parity matters, run the same workflow against each engine you support.

Fresh browser versus an existing session

A newly launched browser starts with an independent session. This is the safer default for repeatable automation because cookies, tabs, and local storage are created for that run.

Playwright also documents ways to connect to an already-running browser, including channel-based and CDP approaches and the Playwright Extension. The extension path is useful when the workflow must reuse existing tabs or a logged-in session.

Session type	Best fit	Trade-off
Fresh browser	Repeatable tasks, isolated credentials, automation from a clean state	You must authenticate inside the workflow when the site requires it.
Existing browser	Existing tabs, a logged-in account, or a manual session that the agent must continue	The result depends on the current browser state and permissions.

Use the connection method documented for your Playwright MCP version and client. Do not copy a connection flag from another MCP browser server and assume it has the same meaning.

Configure capabilities deliberately

The capabilities documentation describes opt-in capability selection and recommends enabling only the capabilities needed for the use case. Start with the smallest useful set, then add capabilities when a workflow requires them.

List the browser actions your agent must perform.
Enable the corresponding documented capability.
Remove capabilities that are not needed by the workflow.
After changing capabilities, restart the server and confirm that the expected tools are visible.

Limiting the tool surface makes the workflow easier to understand and reduces accidental actions. The exact capability names and configuration syntax should come from the current Playwright MCP documentation.

Viewport, device, proxy, and JSON configuration

The official options documentation covers device emulation, viewport size, proxy settings, JSON configuration, and standalone HTTP server setup. These options address different deployment needs:

Device emulation: use a documented device profile when the workflow must resemble a mobile or tablet browser.
Viewport: set a known width and height when responsive layout affects the workflow.
Proxy: route browser traffic through a proxy when your network requires it.
JSON configuration: keep a larger set of server options in a configuration file instead of a long command line.
Standalone HTTP server: use the documented HTTP deployment when the MCP client and browser server run in separate environments or the host has no display.

Because option names and defaults can change, copy the exact syntax from the current Playwright options documentation for the version you install.

A practical headless workflow

Install Node.js 20 or newer.
Confirm that your MCP client supports adding a server.
Add the Playwright MCP definition with npx and --headless.
Restart the client and verify that Playwright tools appear.
Navigate to a public page and read its accessibility snapshot.
Interact with one element, such as a link or form field.
For an authenticated task, decide whether to use a fresh login flow or a documented existing-session connection.
When the workflow is stable, add only the browser, viewport, proxy, and capability options it actually needs.

Common errors and fixes

Symptom	Likely cause	Fix
The client shows no Playwright tools.	The server entry is in the wrong configuration location, or the client has not reloaded it.	Check the client’s MCP setup instructions, validate the JSON, save it in the documented location, and restart the client.
`npx` cannot start the server.	Node.js is missing, too old, or unavailable on the client’s PATH.	Install Node.js 20 or newer and verify the same executable is available to the MCP client process.
A browser window appears.	The server was started without the headless argument.	Add `--headless` to the Playwright MCP server arguments and restart the client.
The browser cannot launch on a remote host.	The environment lacks a display or has host-specific browser dependencies.	Use the documented headless or standalone HTTP deployment options and follow the browser installation requirements for that host.
An authenticated page opens signed out.	The workflow started a fresh browser context.	Automate login in the fresh context or use a documented existing-browser connection when an existing session is required.
An action cannot find an element.	The page has not reached the expected state, the element is not exposed in the current accessibility snapshot, or the selector is wrong.	Inspect the current page state, wait for the required navigation or content, and use the element information returned by the MCP server.
The page behaves differently across browsers.	Different engines can render or execute site code differently.	Choose the engine that matches your supported browser, or run the workflow against each required engine.
The server starts locally but not in the client.	The client process has a different PATH, working directory, or environment.	Use absolute paths where the client allows them, verify environment variables, and inspect the client’s MCP logs.

Performance and reliability practices

Start with a small, deterministic task before adding authentication, file downloads, or multiple pages.
Keep capability scope narrow so the agent has fewer irrelevant tools to evaluate.
Use a fixed viewport and browser engine when visual output or responsive behavior matters.
Prefer a fresh session for repeatable jobs; use existing sessions only when their state is part of the requirement.
For remote deployments, keep the MCP client, server, browser, and network assumptions documented together.
Record the browser choice, configuration, target URL, and session type for each automation job so failures can be reproduced.
Do not describe a workflow as reliable based on configuration alone. Validate it against the pages, authentication flows, and browser engines you intend to support.

Security checklist

Keep credentials out of prompts, source control, and shared MCP configuration files.
Use an isolated browser session for tasks that should not inherit personal cookies or tabs.
When reusing a logged-in browser, confirm that the MCP client and server are trusted by the account owner.
Grant only the capabilities needed for the workflow.
Review proxy and network settings before sending authenticated traffic through a remote host.

Or skip the browser setup

If your goal is a clean screenshot or PDF rather than interactive browser control, ScreenshotNeo provides a single GET request for a URL. Its capture pipeline accepts cookie and consent banners like a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets, and lets each cleanup step be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; the response identifies the result with X-Page-Verdict and X-Billed headers.

See the ScreenshotNeo API documentation for all options, including full-page capture, element selectors, dark mode, device presets, retina scale, PDFs, custom CSS and JavaScript, clicks, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, caching, signed links, asynchronous jobs, webhooks, bulk capture, usage data, and the OpenAPI specification.

cURL

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

Python

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

Node.js

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

ScreenshotNeo has an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots, and every feature is available on every plan.

Create your free ScreenshotNeo account and use the API or MCP server when you need clean captures without maintaining browser infrastructure.

FAQ

Does every MCP browser server use `--headless`?

No. This article documents the Playwright MCP configuration. Other MCP browser servers can use different package names, flags, transports, and setup locations.

Can I use Playwright MCP without an MCP client?

The documented setup assumes an MCP client. Playwright also documents standalone HTTP server deployment for environments where the client and server need to be separated.

Can the agent use my existing browser tabs?

Yes, when you use one of Playwright’s documented existing-browser connection methods, including the extension path. This is appropriate for workflows that require existing tabs or logged-in sessions.

Should I always use headless mode?

Use headless mode for unattended or display-free environments. Headed mode can be useful while diagnosing a workflow because you can observe the browser, but the documented guide describes headed mode as the default.

Is ScreenshotNeo a replacement for interactive browser automation?

No. Playwright MCP is for agent-driven navigation and interaction. ScreenshotNeo is useful when the output you need is a screenshot or PDF and you want the browser setup and page cleanup handled by an API.