{
  "markdown": "# zen-mcp\n\nThe first MCP server for **Zen Browser**. Automate Zen from Claude Code, Cursor, or any MCP client.\n\nNo Selenium. No Playwright. No browser drivers. Just WebSocket.\n\n## Setup (2 minutes)\n\n### 1. Start Zen with remote debugging\n\n```bash\n/Applications/Zen.app/Contents/MacOS/zen --remote-debugging-port 9222\n```\n\n> **Pro tip**: Add `alias zen='open /Applications/Zen.app --args --remote-debugging-port 9222'` to your shell config. Then just run `zen`.\n\n### 2. Add to Claude Code\n\n```bash\n# Option A: npm (recommended)\nnpm install -g zen-mcp\n\n# Option B: Clone\ngit clone https://github.com/sh6drack/zen-mcp.git && cd zen-mcp && npm install\n```\n\nAdd to `~/.claude/mcp_servers.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"zen-browser\": {\n      \"command\": \"zen-mcp\"\n    }\n  }\n}\n```\n\n> If you cloned instead of npm install, use `\"command\": \"node\", \"args\": [\"/absolute/path/to/zen-mcp/server.mjs\"]`\n\nAdd to `~/.claude/settings.json`:\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\"mcp__zen-browser__*\"]\n  }\n}\n```\n\n**That's it.** Start a new Claude Code session and the `zen_*` tools are available.\n\n## 20 Tools\n\n### Browse\n\n| Tool | What it does |\n|------|-------------|\n| `zen_navigate` | Go to a URL |\n| `zen_list_pages` | List all open tabs |\n| `zen_select_page` | Switch to a tab |\n| `zen_new_tab` | Open a new tab |\n| `zen_close_tab` | Close a tab |\n\n### See\n\n| Tool | What it does |\n|------|-------------|\n| `zen_snapshot` | Page structure with selectors (filter: all/interactive/form) |\n| `zen_screenshot` | Capture a screenshot |\n| `zen_get_page_text` | Get page title, URL, and text |\n| `zen_get_form_fields` | List all form fields with labels and values |\n\n### Interact\n\n| Tool | What it does |\n|------|-------------|\n| `zen_click` | Click an element |\n| `zen_fill` | Type into an input or textarea |\n| `zen_select_option` | Pick a dropdown option |\n| `zen_check` | Toggle a checkbox or radio |\n| `zen_press_key` | Keyboard input (Enter, Tab, Ctrl+A, etc.) |\n| `zen_fill_form` | Fill multiple fields at once |\n| `zen_scroll` | Scroll the page or to an element |\n\n### Utility\n\n| Tool | What it does |\n|------|-------------|\n| `zen_evaluate` | Run JavaScript in the page |\n| `zen_wait` | Wait N milliseconds |\n| `zen_wait_for` | Wait for text or element to appear |\n| `zen_reconnect` | Force reconnect to Zen |\n\n## How It Works\n\n```\nClaude Code  ──stdio/MCP──>  zen-mcp  ──WebSocket/BiDi──>  Zen Browser\n```\n\nzen-mcp speaks **WebDriver BiDi** (W3C standard) directly over WebSocket. Form filling uses native value setters with `input`/`change` event dispatch so React, Vue, and Angular apps work correctly.\n\n### What Works Well\n\n- **Navigation, clicking, form filling** — rock solid, handles React/Vue/Angular\n- **Screenshots and page reads** — reliable content extraction\n- **Tab management** — open, close, switch between tabs\n- **JavaScript evaluation** — run any code in the page context\n- **Keyboard input** — shortcuts, Enter, Tab, modifier combos\n\n### Known Limitations\n\n- Zen inherits Firefox's WebDriver BiDi implementation, which is still maturing. Some advanced BiDi commands that work in Chrome may not be available yet.\n- Zombie sessions can only be cleared by restarting Zen (BiDi session.end is connection-scoped). zen-mcp detects this and tells you what to do.\n- No file upload or drag-and-drop support (BiDi spec limitation).\n\n### Built-in Reliability\n\n- **Auto-reconnect** with exponential backoff if WebSocket drops\n- **Zombie session recovery** when a previous client crashed\n- **Connection retry** (3 attempts with backoff)\n- **Clean shutdown** on SIGINT/SIGTERM to prevent orphaned sessions\n\n## Troubleshooting\n\n| Problem | Fix |\n|---------|-----|\n| \"Cannot connect to Zen Browser\" | Start Zen with `--remote-debugging-port 9222` |\n| \"Maximum number of active sessions\" | Restart Zen: `killall zen && zen` |\n| Connection keeps dropping | Use `zen_reconnect` to force a fresh connection |\n\n## Config\n\n| Env Variable | Default | Description |\n|-------------|---------|-------------|\n| `ZEN_DEBUG_PORT` | `9222` | Zen's remote debugging port |\n\n## Requirements\n\n- [Zen Browser](https://zen-browser.app/)\n- Node.js 20+\n\n## Test\n\n```bash\nnode test-e2e.mjs   # 21 tests, needs Zen running\n```\n\n## License\n\nMIT\n",
  "bytes": 4231,
  "sha": "744691b78fb5f79d94a913480deac3ea0eacd023b0481c13215f12e9ef0240bb",
  "repo_slug": "sh6drack/zen-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sh6drack_zen_mcp_f5dbd263/readme"
}