To connect Zen Browser to an MCP client, run Zen with its WebDriver BiDi debugging port open, install the zen-mcp server, register that server as a local MCP command, and start a new client session. On macOS, the essential commands are:
/Applications/Zen.app/Contents/MacOS/zen --remote-debugging-port 9222
npm install -g zen-mcpAfter adding zen-mcp to your client configuration, the client should expose the server’s zen_* tools for tabs, page inspection, screenshots, forms, JavaScript, and navigation.
What this setup does
This is a local bridge. Your MCP client (such as Claude Code or Cursor) starts zen-mcp; the server then connects to the running Zen Browser over WebDriver BiDi through a WebSocket. The project describes its approach as “No Selenium. No Playwright. No browser drivers. Just WebSocket.” It does not add Selenium, Playwright, or a separate browser driver.
The repository documents 20 tools grouped into four areas:
#1 Best Overall
- Browse: navigate, list, select, open, and close tabs.
- See: inspect page structure, read page text, inspect form fields, and take screenshots.
- Interact: click, fill, select options, toggle controls, submit forms, press keys, and scroll.
- Utility: evaluate JavaScript, wait for page conditions, and reconnect.
That combination is suitable for research, data extraction, form completion, and lightweight browser workflows. It is not a read-only connection: an agent can change pages, submit forms, and interact with an authenticated profile.
Prerequisites
- Zen Browser installed on the computer where the MCP client runs.
- Node.js 20 or newer, with npm available on your
PATH. - An MCP client that can launch a local stdio server command.
- A free local TCP port, using
9222in the documented example.
Install Zen and Node.js using their normal installers for your operating system. The command and application path below are the repository’s macOS example; on another operating system, use that installation’s Zen executable path and equivalent argument syntax.
Step 1: Start Zen with remote debugging
macOS executable command
Quit Zen first if it is already running, then launch the executable with the debugging port:
/Applications/Zen.app/Contents/MacOS/zen --remote-debugging-port 9222Keep this Zen process running while the MCP client uses it. The repository also suggests launching the application bundle with arguments:
open /Applications/Zen.app --args --remote-debugging-port 9222Only one process needs to own the port. If another application is listening on 9222, choose an unused port and use the corresponding server setting if the version of zen-mcp you install supports a custom port.
Check the startup before configuring the client
- Confirm that Zen opened normally rather than exiting immediately.
- Confirm that you started the same Zen profile you intend to expose.
- Leave the terminal or application process running; closing it ends the debugging endpoint.
Step 2: Install zen-mcp
Global npm installation
The shortest setup installs the published command globally:
npm install -g zen-mcpVerify that your shell can find it:
which zen-mcp
zen-mcp --helpOn Windows, use the platform’s equivalent command lookup (for example, where zen-mcp). If the command is not found after installation, fix npm’s global bin directory in your PATH or invoke the installed executable by its full path.
Run from a cloned repository
For a local checkout, clone the project, install dependencies, and point the MCP client at its server file:
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #2
git clone https://github.com/sh6drack/zen-mcp.git
cd zen-mcp
npm install
node server.mjsThe client normally starts the command for you, so do not run a second copy manually unless you are diagnosing the connection. A local checkout is useful when you need to inspect or update the server independently of the global npm package.
Step 3: Register the server in an MCP client
Claude Code
Add a server entry to the MCP configuration used by Claude Code:
{
"mcpServers": {
"zen-browser": {
"command": "zen-mcp"
}
}
}If you use the cloned checkout instead, replace the command with the absolute path to Node and the repository’s server.mjs. Absolute paths avoid failures caused by a client starting with a different working directory or PATH.
Cursor and other MCP clients
Cursor and other clients use the same basic information: a server name and a local command. Open the client’s MCP settings, add a local or stdio server, set the command to zen-mcp, and save. If the UI requests a JSON configuration, the equivalent entry is:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problems{
"mcpServers": {
"zen-browser": {
"command": "zen-mcp"
}
}
}Some clients call the field “Command,” “Executable,” or “stdio server.” Do not enter an HTTP URL for this setup; the documented bridge is a locally launched process.
Start a fresh session
Restart the client or create a new chat/session after saving the configuration. The repository says the zen_* tools should then appear. Ask the client to list open tabs as a harmless smoke test before allowing it to fill a form or run JavaScript.
Step 4: Use the tools safely
Navigation and tabs
- Ask the agent to list existing tabs.
- Open a new tab or select a specific tab.
- Navigate to the target URL.
- Wait for the page condition or load state you need.
Keeping tab selection explicit prevents an agent from acting on the wrong page when several windows are open.
Inspection and extraction
Use page-structure inspection before clicking. Read visible text and inspect form fields to discover labels, names, and available controls. For dynamic pages, wait for a selector or condition rather than assuming the initial HTML is complete.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Interaction
The interaction tools cover clicks, text entry, option selection, toggles, key presses, scrolling, and multi-field form filling. Treat submit, delete, purchase, and account-setting controls as confirmation points: inspect the page, summarize the intended action, and require human approval before the final click.
Screenshots and JavaScript
Take a screenshot when visual state matters, and use JavaScript evaluation only when a normal inspection or interaction tool cannot express the operation. JavaScript runs in the connected browser context, so it can read or modify page state available to that profile.
Security and profile isolation
An agent attached to an existing browser session may read and interact with authenticated pages, cookies, and other profile state. This is the same trust concern highlighted in Chrome for Developers’ “Get started with Chrome DevTools for agents” guidance and applies to Zen as well.
- Use a separate Zen profile for MCP work whenever possible.
- Do not connect an untrusted agent to a profile containing email, banking, administration, or corporate sessions.
- Review the current tab and URL before every sensitive action.
- Assume that page text, cookies, and authenticated content are available to the agent.
- Close the debugging-enabled browser when the workflow is complete.
Common errors and fixes
“Cannot connect to Zen Browser”
Cause: Zen was started normally, the debugging port is wrong, or the browser process has exited.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallFix: Quit Zen, relaunch it with --remote-debugging-port 9222, keep it running, and then restart the MCP client session. If you selected another port, ensure the server and browser use the same one.
“Maximum number of active sessions”
Cause: A previous or crashed connection left a zombie session.
Fix: Close client sessions and restart Zen. The repository gives this macOS recovery command:
killall zen && zenAfter the restart, launch Zen again with the debugging argument and reconnect the client.
WebSocket connection dropped
Cause: Zen restarted, the debugging process ended, or the network endpoint became unavailable.
Fix: Use the server’s zen_reconnect utility. If that fails, restart Zen with the debugging port and create a new MCP session.
Tools do not appear
Cause: The client has not reloaded its configuration, cannot find zen-mcp, or the JSON is malformed.
Fix: Run which zen-mcp, use an absolute executable path if necessary, validate the JSON, and restart the client rather than only reopening the chat.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →File upload or drag-and-drop fails
File uploads and drag-and-drop are currently unsupported because of WebDriver BiDi limitations in this project. Use a supported text/form interaction, a manually completed upload, or a different automation path for that step.
An advanced browser command is unavailable
Some BiDi commands available in Chrome may not yet be available in Firefox-derived Zen. Replace the operation with the documented inspection, interaction, wait, or JavaScript tools, or complete that specific step manually.
Reliability, performance, and operating costs
Keep sessions short and explicit
Reuse one running Zen process for a focused workflow, but reconnect after crashes or long idle periods. Listing tabs and waiting for selectors makes workflows more deterministic than issuing clicks immediately after navigation.
Control page complexity
Large pages, client-side rendering, redirects, and authentication can increase wait time. Ask the agent to wait for a meaningful selector or page condition, and limit extraction to the fields required for the task.
Recommended Free Tools
Best Value
Local resource use
The browser, Node process, and MCP client all run locally. The documented project does not provide an independent uptime, latency, or adoption statistic, so treat reliability as dependent on your machine, Zen version, network, and the specific site.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is a clean website image rather than interactive browsing, ScreenshotNeo provides a one-request screenshot API. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
See the parameter reference in the ScreenshotNeo documentation. The following calls capture Stripe’s homepage; replace the URL with your target.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.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://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));ScreenshotNeo includes full-page and element capture, device presets and custom viewports, dark mode, retina scale, PDF controls, HTML/CSS rendering, custom CSS and JavaScript, clicks, selector waits, network-idle waits, request blocking, headers, cookies, user agents, timezone and geolocation, transparent backgrounds, resizing, configurable caching, signed links, asynchronous webhooks, bulk capture for up to 100 URLs per call, a usage API, and an OpenAPI specification. Its 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. Sign up for the free plan.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
When to choose Zen MCP instead
Use Zen MCP when an agent must operate a live browser: inspect a page, move through tabs, fill controls, evaluate page JavaScript, or handle a workflow that depends on an existing session. Use an API such as ScreenshotNeo when the deliverable is a repeatable screenshot or PDF and you do not need interactive tab or form control.
Frequently Asked Questions
Can I connect zen-mcp to a Zen window that is already open?
Only if that Zen process was started with the remote debugging option. A normally launched window does not expose the endpoint required by the server; restart Zen with –remote-debugging-port 9222.
Does zen-mcp require Selenium or Playwright?
No. The project uses WebDriver BiDi over WebSocket and explicitly says it uses no Selenium, Playwright, or browser drivers.
Which operations are not supported?
File uploads and drag-and-drop are unsupported because of current WebDriver BiDi limitations. Some advanced commands documented for Chrome may also be unavailable in Firefox-derived Zen.
What should I do before letting an agent use a logged-in account?
Use a separate browser profile or a trusted agent, inspect the active tab, and remember that the connection can read authenticated pages, cookies, and profile state and can perform write actions.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
