A Simple MCP Server Example for Browser Automation

To set up an MCP server for browser automation, run Microsoft Playwright MCP from an MCP client. You need Node.js 20 or newer and a compatible MCP client. The client starts the server, discovers its browser tools, and lets an AI assistant call those tools to navigate and interact with a page. Playwright MCP is the browser automation server; MCP is the connection that makes its tools available to the client. Microsoft’s Playwright MCP project and its getting-started guide are the primary references for setup. [c001, c005]

1. What you need

Node.js 20 or newer. Confirm your installed version with node --version.
An MCP client that supports adding a server. The exact configuration location and restart or reload step depend on the client.
Network access to the pages you want the browser to visit. The server’s browser download is described as automatic on first use.

The minimal setup below uses npx to launch the package. It is a convenient starting point because the client can start the server on demand. Since @latest moves as new package versions are published, use the package’s versioning guidance and pin an appropriate version when you need repeatable installs. Recheck the current client instructions, flags, and requirements before sharing a long-lived configuration. [c001]

2. Add the Playwright MCP server to your client

Add this server entry to the MCP configuration used by your chosen client:

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

Save the configuration and use the client’s documented reload or restart action so it starts the server. The JSON is the server entry, not a universal configuration file: client-specific files and setup screens differ. Consult the official guide for the client you use, including VS Code, Cursor, Claude Code, or Claude Desktop. [c001]

Check that Node.js is at least version 20.
Find the MCP server configuration instructions for your client.
Insert the playwright entry in the appropriate configuration structure.
Reload the client, then confirm that Playwright browser tools are available to the assistant.
On first use, allow time for the browser download if it has not already been installed.

3. Run the first browser automation task

Ask the assistant to complete the documented starter task: “Navigate to https://demo.playwright.dev/todomvc and add a few todo items.” The assistant uses the browser tools exposed by Playwright MCP. A typical interaction is to navigate, inspect the page’s accessibility snapshot, identify the textbox, enter a todo, and inspect or interact with the resulting checkbox and list. [c001]

Playwright MCP gives the AI client structured page information and browser actions to work with.

The important detail is that the interaction can use a structured accessibility snapshot, not only a screenshot. The snapshot exposes semantic information such as element roles, visible text, and references that can be used in later actions. For example, a snapshot may identify a textbox and checkbox with references; the model can use those references to enter an item and toggle its completion state. That gives the model a structured description of the page to act on. The precise sequence of tool calls depends on what the page returns and what the client displays. [c001]

When prompting for a reliable task, name the destination, the changes to make, and how to confirm them. For example: “Open the TodoMVC demo, add ‘Review pull request’ and ‘Update docs’, then report the visible items and whether either is marked complete.” A clear confirmation step helps distinguish successful interaction from an attempted action.

4. Keep the tool surface small

Playwright MCP exposes core browser actions by default, including navigation, snapshots, clicks, and typing. Its documentation also describes optional capability groups, such as network, storage, testing, vision, PDF, and developer tools. Start with the core tools; enable an additional group only when a workflow needs it. The project’s guidance says a smaller exposed tool set reduces schema and context load and makes tool selection less confusing. [c003]

Need	Configuration choice
Navigate and interact with ordinary pages	Use the default core browser tools.
Inspect or work with a specialized capability	Enable only the documented optional group needed for that task.
Let an operator see browser activity	Use the default headed mode, where a display is available.
Run where there is no display	Use the documented `--headless` option.

Capability names and flags may change; check the current project configuration reference before adding them. More enabled tools are not automatically better: they broaden what the assistant can select and can make the client’s tool descriptions larger. [c003, c004]

5. Choose browser mode and transport

Headed or headless

The browser is headed by default. Use that when an operator needs to watch the session and the environment has a display. The configuration reference documents --headless for environments where the browser should run without a visible window. Headless operation does not change the need to inspect outcomes: have the assistant report the resulting page state, and retain logs appropriate to your environment. [c004]

Local stdio or standalone HTTP

The quick-start configuration launches a local process using npx, which is the simplest arrangement for a client that supports local server processes over stdio. The project also documents a standalone HTTP server and connecting a client to its /mcp endpoint. Use HTTP only where the client and deployment design call for it; decide deliberately which network interfaces can reach the server and what browser resources it can access. A reachable endpoint is not safe by default simply because it speaks MCP. [c001, c004]

6. Treat browser access as an operational boundary

A browser automation server can reach destinations and use browser state available to its process. Before giving an agent access, consider which network destinations it can reach, whether it uses an authenticated browser profile, and whether local files are accessible. The repository documents controls such as allowed hosts and origins and file-access restrictions, along with options that can grant access. Configure these to match the job and environment; a setting is a control to review, not proof that a deployment is secure. [c005]

The secrets-file feature can redact matching plain-text secrets in tool responses and substitute placeholders when typing. The project explicitly cautions: “This is a convenience, not a security boundary.” Do not treat redaction as a replacement for limiting credentials, browser profile access, network destinations, or server exposure. [c004]

Use only the browser profile and credentials the task requires.
Review permitted hosts, origins, and file access against the workflow.
Keep a standalone server’s network reachability intentional.
Do not put broad credentials into prompts or assume response redaction prevents every form of disclosure.

7. Troubleshooting

Symptom	Likely cause	What to do
Client does not show Playwright tools	Configuration is in the wrong client location, JSON is invalid, or the client has not reloaded.	Use the client-specific setup guide, validate the JSON structure, and restart or reload the client as documented.
`npx` cannot start the package	Node.js is missing or older than the documented requirement, or package retrieval is unavailable.	Check `node --version`; install Node.js 20 or newer and ensure the environment can retrieve the package.
First browser action is slow or unavailable	The browser may need its first-use download, or the environment lacks required network access.	Allow the initial browser setup to complete and check download/network access under the environment’s policies.
Assistant cannot find a control	The page snapshot may not expose the expected role or text, or the page has not reached the relevant state.	Ask for a fresh snapshot, describe the intended control and state, and wait for the page to render before acting.
Browser window is not visible	The server is running in headless mode or the environment has no display.	Remove `--headless` when visibility is needed and supported, or inspect results through the client’s returned page state.
Client cannot reach an HTTP server	Address, port, endpoint, or network routing does not match the standalone server setup.	Check the server and client HTTP configuration against the current guide, including the `/mcp` endpoint.
A secret appears in a response or behavior is unexpected	Redaction is limited to configured matching text and is only a convenience.	Review the secrets configuration, reduce credential exposure, and tighten profile and destination access; do not rely on redaction as a security boundary.

8. Performance, reliability, and cost

The sources reviewed do not establish a numeric speed benchmark, reliability guarantee, or usage price for Playwright MCP, so none should be assumed. Runtime depends on the target page, browser startup and download state, network, and the interactions the agent performs. A smaller tool surface can reduce schema and context load according to the project’s documentation; it does not guarantee a particular latency or task success rate. [c003]

For repeatable runs, pin the package version using the project’s current package guidance instead of relying indefinitely on @latest. Make prompts state an observable completion condition, and handle navigation or page-state changes by requesting fresh page information before the next action. Browser work remains sensitive to external page changes and access conditions, so avoid treating a successful configuration as a guarantee every target page will behave identically.

The setup uses software: Node.js, an MCP client, and the Playwright MCP package. No physical product or supported partner recommendation follows from the documented workflow.

9. When MCP is the right interface

The Playwright documentation frames MCP as useful for specialized agent loops and exploratory automation, where the agent makes structured tool calls. It presents Playwright CLI as a fit for coding agents working in large codebases and notes lower token cost in its comparison. This is the vendor’s framing, not a universal benchmark; choose based on your client, workflow, and need for an interactive tool interface. [c002]

Use this MCP example when the AI client needs to explore a live page and interact with it through browser tools. If the task is simply to produce a page image or PDF, a screenshot API may avoid maintaining browser installation and MCP client configuration yourself.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request can return a screenshot or PDF. Its capture flow accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and any MCP client. Every feature is on every plan. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Yearly billing gives two months free.

For a simple capture, request the API with 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}`);

See the ScreenshotNeo API documentation for the request options. Create a free account for 1,000 screenshots a month, with no card required.

10. FAQ

Does MCP itself control a browser?

MCP connects the client to tools. In this setup, Playwright MCP is the server that supplies Playwright-backed browser automation tools. [c005]

Does the assistant interact using only screenshots?

No. The documented example uses structured accessibility snapshots containing roles, text, and references that the model can use for subsequent actions. [c001]

Should I enable every optional capability group?

No. Begin with core tools and add only the documented capabilities a workflow needs. [c003]

Is `@latest` suitable for a locked-down or repeatable environment?

It is the getting-started configuration, but it is a moving package tag. Follow current package guidance and pin a version when repeatability matters. [c001]

Can I use a remote server?

The project documents standalone HTTP operation and a client connection to its /mcp endpoint. Configure exposure and browser access deliberately for the deployment. [c004, c005]