# zen-mcp

Automates Zen Browser through WebDriver BiDi over WebSocket. It lets your coding assistant read pages, click elements, and submit forms without external drivers.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 24
- Author: sh6drack
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/sh6drack/zen-mcp
- Updated: 2026-05-16
- HTML: https://affpapa.org/en/nevibecode/mcp/zen-mcp

## What it 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`.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `ZEN_DEBUG_PORT` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env ZEN_DEBUG_PORT=<ZEN_DEBUG_PORT> --transport stdio zen-mcp -- npx -y zen-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add zen-mcp --env ZEN_DEBUG_PORT=<ZEN_DEBUG_PORT> -- npx -y zen-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "zen-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "zen-mcp"
            ],
            "env": {
                "ZEN_DEBUG_PORT": "<ZEN_DEBUG_PORT>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "zen-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "zen-mcp"
            ],
            "env": {
                "ZEN_DEBUG_PORT": "<ZEN_DEBUG_PORT>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e ZEN_DEBUG_PORT=<ZEN_DEBUG_PORT> zen-mcp npx -y zen-mcp
```
Replace <…> with your own values

## When to use it
- 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
- 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

## Similar
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [AIHawk](https://affpapa.org/en/nevibecode/mcp/aihawk.md) — MCP server · ★ 32221
- [Skyvern](https://affpapa.org/en/nevibecode/mcp/skyvern.md) — MCP server · ★ 23263
- [SeleniumBase MCP](https://affpapa.org/en/nevibecode/mcp/seleniumbase-mcp.md) — MCP server · ★ 13169
- [apify-mcp-server](https://affpapa.org/en/nevibecode/mcp/apify-mcp-server.md) — MCP server · ★ 12927

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md