ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Configure Playwright MCP in Cherry Studio

Add Playwright MCP to Cherry Studio with the right Node.js setup, arguments, browser options, activation steps, and fixes for common errors.

By the ScreenshotNeo team1 October 20267 min read

To configure Playwright MCP in Cherry Studio, add a manual STDIO server with npx as the command and @playwright/mcp@latest as the argument. Then enable the MCP Server control in the chat before asking the model to browse.

Prerequisites

  • Node.js 20 or newer. Cherry Studio launches the npx process, so Node.js must be installed and visible in the environment Cherry Studio uses.
  • An MCP-capable Cherry Studio installation. The workflow below uses Cherry Studio’s manual MCP server form.
  • Network access. The first launch may need to download the Playwright MCP package and browser components.

The official Playwright documentation describes the Playwright MCP server as providing browser automation capabilities through the Model Context Protocol. See the Playwright MCP documentation for the current prerequisite and option details.

1. Add Playwright MCP as a STDIO server

  1. Open Settings in Cherry Studio.
  2. Open MCP Server.
  3. Click Add Server.
  4. Choose STDIO as the server type.
  5. Set the name to playwright (any clear name works).
  6. Set Command to npx.
  7. Set Arguments to @playwright/mcp@latest.
  8. Save the server.

Cherry Studio’s documentation describes the required fields as name, type, command and arguments, followed by saving the server. If your build uses a tokenized argument editor, keep the package as one argument.

Equivalent configuration

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

Cherry Studio stores these same values through its form; you do not normally need to create this JSON file manually. The equivalent structure is useful when checking a configuration exported from another MCP client.

2. Add optional browser arguments

Optional flags go after the package name in the argument list.

Goal Arguments
Run without a visible browser window @playwright/mcp@latest --headless
Use Firefox @playwright/mcp@latest --browser=firefox
Use WebKit @playwright/mcp@latest --browser=webkit
Use Microsoft Edge @playwright/mcp@latest --browser=msedge
Use Chrome @playwright/mcp@latest --browser=chrome
Load a configuration file @playwright/mcp@latest --config path/to/config.json
Use a fresh browser context @playwright/mcp@latest --isolated

In a list editor, enter each token separately:

@playwright/mcp@latest
--headless
--browser=firefox

If Cherry Studio presents one text field, enter the same values separated by spaces:

@playwright/mcp@latest --headless --browser=firefox

Use the exact tokenization expected by your Cherry Studio version. A path containing spaces may need the quoting convention supported by that field or an absolute path without spaces.

3. Enable the server in a conversation

  1. Open or reopen a chat after saving the server.
  2. Find the MCP Server control in the chat box.
  3. Turn it on.
  4. Confirm that the playwright entry is enabled for that conversation.

Saving a server does not automatically make its tools available in every existing conversation. The model must have the server enabled before it can call browser tools.

4. Verify the connection safely

Start with a small request that does not require login or sensitive data:

  1. Ask the model to navigate to https://example.com.
  2. Ask it to report the page title.
  3. Ask it to take a screenshot.

If the title request works and the screenshot tool appears, the STDIO process and chat activation are both functioning. These steps are a smoke test, not a performance benchmark.

Common setup choices

Headed versus headless

Headed mode is the default and opens a visible browser window. It is useful while diagnosing navigation, consent dialogs or authentication. Add --headless for background automation or environments without a display.

Chromium versus Firefox, WebKit or Edge

Chromium is the default path for many sites. Use --browser=firefox, --browser=webkit, --browser=msedge or --browser=chrome when you need to check a specific engine. Browser behavior can differ, so reproduce a site issue in the engine where it occurs.

Persistent versus isolated profiles

The default persistent profile can preserve state between launches, but only one process can use a profile at a time. Add --isolated when you need a clean context, parallel sessions or a way around a stale profile lock.

Manual versus automatic installation

Cherry Studio documents automatic MCP installation for version 1.1.18 or higher, but labels that workflow beta and warns that manual parameter edits may still be needed. Use the manual STDIO form when automatic installation does not produce a usable entry.

HTTP transport when STDIO is unsuitable

STDIO is the simplest option because Cherry Studio owns the local child process. If your client cannot manage a local process, run the server separately with an HTTP port:

npx @playwright/mcp@latest --port 8931

Then configure Cherry Studio with an MCP URL ending in /mcp, using the HTTP transport fields provided by your Cherry Studio version. Keep the terminal process running while the conversation uses the server.

Troubleshooting

Symptom Likely cause Fix
Server will not start Node.js is missing, too old or unavailable to Cherry Studio’s npx process. Install Node.js 20 or newer, verify node --version and npx --version in the same account/environment, then restart Cherry Studio.
npx is not found Cherry Studio was started without the shell PATH that contains Node.js. Start Cherry Studio from an environment with Node.js on PATH, or use the runtime/environment installation controls documented by your Cherry Studio build.
Profile lock error Another Playwright or Chromium process is using the persistent profile. Close stale browser processes and retry, or add --isolated to use a fresh profile.
No tools appear in chat The MCP Server control is off, the server is disabled for the conversation or the chat was opened before the server was saved. Reopen the conversation, enable MCP Server and confirm the Playwright entry is active.
Package download fails Network, proxy, registry or permission problems prevent npx from resolving the package. Check the network and npm registry access available to Cherry Studio, then retry the command outside Cherry Studio to expose the underlying error.
Firefox or another engine will not launch The requested browser dependency is unavailable or the flag is misspelled. Use the documented form --browser=firefox (or another supported value), then install the required Playwright browser components if prompted.
Configuration file is ignored The path is relative to a different working directory or the argument was split incorrectly. Try an absolute path and ensure --config and its path are separate arguments in a list editor.
Headless mode still shows a window The flag was entered before the package, or Cherry Studio stored the entire line as one incorrect token. Place --headless after @playwright/mcp@latest and follow the field’s tokenization rules.
HTTP client cannot connect The separate server process is not running, the port is blocked or the URL does not end in /mcp. Keep the --port 8931 process running, check local firewall rules and use the correct MCP endpoint.

Performance, reliability and cost considerations

  • Startup time: The first npx launch may download packages or browser components. Subsequent launches can be faster when the local cache is available.
  • Profile stability: A dedicated isolated profile avoids lock contention and state left by another session. A persistent profile is useful only when you intentionally need its saved state.
  • Browser choice: Headless mode removes display requirements. The browser engine still determines compatibility with the target site.
  • Network reliability: Navigation depends on the target site’s availability, DNS, proxy and authentication state. Repeated failures should be separated into client startup errors and page-load errors.
  • Resource use: Each active browser context consumes local CPU and memory. Close unused conversations or server processes when running several sessions.
  • Cost: Playwright MCP itself is software launched through npm/npx; any infrastructure, network or model costs depend on your environment and provider. No product pricing claim is implied by this setup guide.

Or skip the browser setup

If your goal is to obtain clean website screenshots instead of giving an AI agent an interactive browser, ScreenshotNeo provides a single screenshot API request. Before capture it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets. Each step can be turned off.

Only clean shots are billed. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits cost nothing, and the response identifies the result with X-Page-Verdict and X-Billed headers. ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients.

See the ScreenshotNeo API documentation for all options. This basic call captures a WebP image:

cURL

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

Python

import requests

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

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const body = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', body);

ScreenshotNeo supports full-page and element captures, dark mode, device presets, custom viewports, retina scale, PDF output, custom CSS and JavaScript, waits, request blocking, headers, cookies, user agents, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed links, asynchronous jobs, bulk capture and a usage API. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account and get 1,000 screenshots a month with no card.

FAQ

Does Cherry Studio require a JSON file?

No. The manual form stores the same command and argument values shown in the equivalent JSON example.

Can I use a different npm version tag?

The documented setup uses @playwright/mcp@latest. Pin another version only when your team has a specific compatibility reason and manages that version deliberately.

When should I choose HTTP instead of STDIO?

Choose HTTP when Cherry Studio cannot launch or supervise a local child process, or when the server must run separately from the desktop client.

Why does a new chat matter after configuration?

Cherry Studio exposes MCP tools per conversation. Reopening the chat helps it load the saved server and lets you enable the MCP Server control there.

Is ScreenshotNeo a replacement for Playwright MCP?

They solve different tasks. Playwright MCP gives an AI agent interactive browser automation; ScreenshotNeo gives a direct screenshot or PDF API and also offers MCP tools for capture-focused workflows.

Keep reading