zen-mcp — Claude Code MCP server: what it does, how to install
Automates Zen Browser through WebDriver BiDi over WebSocket. It lets your coding assistant read pages, click elements, and submit forms without external drivers.
claude mcp add --env ZEN_DEBUG_PORT=<ZEN_DEBUG_PORT> --transport stdio zen-mcp -- npx -y zen-mcpWhat zen-mcp does
This server bridges your AI agent directly to Zen Browser using WebSocket connections. Instead of running Playwright or Selenium binaries, it communicates through the W3C WebDriver BiDi protocol. The integration can read page text, capture screenshots, manage tabs, and execute custom JavaScript. Input fields dispatch standard input and change events, ensuring forms built with React or Vue update state properly.
You get 20 dedicated tools covering navigation and DOM inspection. Connection drops trigger automatic retries. Without launching Zen via --remote-debugging-port 9222, the server cannot establish communication.
Running this package requires Node.js 20 or newer. Due to current limitations in the underlying Firefox BiDi engine, drag-and-drop actions and file uploads are unsupported. Stale zombie sessions cannot be reset remotely; clearing them requires restarting the browser binary with killall zen && zen.
What it helps with
- capture screenshots and extract page text inside Zen Browser
- fill out form fields and toggle checkboxes without Playwright
- switch, open, or close browser tabs during an agent session
- evaluate arbitrary JavaScript expressions in the active tab context
Example prompts for the agent
- Open a new tab in Zen Browser and show the interactive form fields
- Take a screenshot of the current page and extract its main text
- Fill out the email and password inputs on the active page, then press Enter
How to install zen-mcp
Platform CLI
claude mcp add --env ZEN_DEBUG_PORT=<ZEN_DEBUG_PORT> --transport stdio zen-mcp -- npx -y zen-mcpReplace <…> with your own values
Platform CLI
codex mcp add zen-mcp --env ZEN_DEBUG_PORT=<ZEN_DEBUG_PORT> -- npx -y zen-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"zen-mcp": {
"command": "npx",
"args": [
"-y",
"zen-mcp"
],
"env": {
"ZEN_DEBUG_PORT": "<ZEN_DEBUG_PORT>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"zen-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"zen-mcp"
],
"env": {
"ZEN_DEBUG_PORT": "<ZEN_DEBUG_PORT>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e ZEN_DEBUG_PORT=<ZEN_DEBUG_PORT> zen-mcp npx -y zen-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about zen-mcp
How do I install zen-mcp in Claude Code?
Run claude mcp add zen-mcp -- npx -y zen-mcp. Before starting your session, launch Zen Browser with --remote-debugging-port 9222 so the server can reach it.
What does zen-mcp do?
It provides 20 tools for controlling Zen Browser via the WebDriver BiDi protocol over WebSocket. The agent can browse tabs, take screenshots, trigger keyboard events, and fill forms.
Why can zen-mcp not connect to Zen Browser?
Zen must be running with the --remote-debugging-port 9222 flag enabled. If a previous session crashed, restart the browser using killall zen && zen or trigger zen_reconnect.
