🌐 Zen Browser MCP

Drive your live Zen Browser (and Firefox) tabs directly from AI Agents (Claude Code, Oh My Pi, Cursor, Zed) via the Model Context Protocol (MCP).

No Chromium required. No heavy vision/screenshot models. Pure DOM-level interaction with zero token waste.

✨ Features

• 🦊 Native Zen Browser & Firefox Support: Built specifically for Gecko using a lightweight WebExtension (Manifest V2).

• ⚡ Lightweight & Blazing Fast: Communicates over local WebSockets (127.0.0.1:9876). Actions execute in milliseconds.

• 🎯 Visual Feedback: When the agent clicks an element, it glows with a bright yellow outline on your screen so you can watch it work.

• 🧠 React & Vue Reactive Input: Input values are dispatched through prototype setters, guaranteeing that modern single-page apps (SPAs) register form changes.

• 🔒 100% Private & Local: All communication stays on your machine loopback. Zero cloud tracking, zero screenshots sent to LLMs.

• 🛠️ Dual Interface: Use it as a native MCP Server for AI models or as a standalone zen-agent CLI tool in your terminal.

Related MCP server: mcp-zen

🏗️ Architecture

┌───────────────────────────┐
│ AI Agent                  │
│ (Claude Code / OMP / ...) │
└─────────────┬─────────────┘
              │ stdio (JSON-RPC 2.0)
┌─────────────▼─────────────┐
│ zen-browser-mcp           │
│ (mcp-server.ts)           │
└─────────────┬─────────────┘
              │ HTTP REST (127.0.0.1:9876)
┌─────────────▼─────────────┐
│ Zen Bridge Server         │
│ (Bun WebSocket server)    │
└─────────────▲─────────────┘
              │ WebSocket (ws://127.0.0.1:9876)
┌─────────────▼─────────────┐
│ Zen Agent WebExtension    │
│ (Zen Browser / Firefox)   │
└───────────────────────────┘

🚀 Quick Start (1 Minute)

1. Clone & Run Installer

git clone https://github.com/KadirBerkpolat1/zen-browser-mcp.git
cd zen-browser-mcp
./install.sh

(If you don't have Bun installed, the script will automatically install it for you).

2. Start the Bridge Server

Run the server in the background:

nohup bun run server/bridge.ts serve >/dev/null 2>&1 &

(Or keep it open in a terminal window: zen-agent serve).

3. Load Extension into Zen Browser

1. Open Zen Browser and navigate to:

   about:debugging#/runtime/this-firefox

2. Click "Load Temporary Add-on..." (Bu Firefox'a Geçici Eklenti Yükle...).

3. Select extension/manifest.json (or the packaged zen-agent.xpi) inside the cloned repo.

4. Verify Connection

In your terminal, run:

zen-agent status

You should see:

✅ Zen Browser bağlı!
   Başlık : YouTube - Home
   URL    : https://www.youtube.com

🔌 AI Agent Configuration (MCP)

Claude Code

Run the native CLI command:

claude mcp add zen-browser bun run /absolute/path/to/zen-browser-mcp/mcp-server.ts

Cursor / Oh My Pi (OMP) / Zed

Add the server to your mcp.json (~/.omp/agent/mcp.json or .cursor/mcp.json):

{
  "mcpServers": {
    "zen-browser": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/zen-browser-mcp/mcp-server.ts"]
    }
  }
}

🧰 Available MCP Tools

When connected, your AI agent has direct access to these typed tools:

💻 Standalone CLI Usage (zen-agent)

You can also control Zen Browser directly from your terminal:

# Check connection
zen-agent status

# Navigate to website
zen-agent goto "https://www.amazon.com"

# Inspect actionable buttons and fields
zen-agent inspect

# Click by index number or text
zen-agent click 4
zen-agent click "Add to Cart"

# Type into search field and submit
zen-agent type "input[type='search']" "mechanical keyboard" --enter

# Scroll down
zen-agent scroll down 600

🇹🇷 Türkçe Özet

Bu araç, Zen Browser (veya Firefox) kullanan geliştiricilerin açık olan sekmelerini Claude Code, OMP ve Cursor gibi yapay zeka ajanlarına bağlamasını sağlar.

• Chromium şartı yok: Zen Browser'ın kendi motoruyla uyumludur.

• Ekran görüntüsü çekmez: Sayfayı HTML kodu üzerinden okur, kotayı tüketmez ve anında tıklar.

• Canlı İzleme: Yapay zekanın tıkladığı butonların etrafında sarı ışık yanar, ne yaptığını canlı izleyebilirsiniz.

Kurulum:

git clone https://github.com/KadirBerkpolat1/zen-browser-mcp.git
cd zen-browser-mcp
./install.sh

🛡️ Security & Privacy

• Safe By Design: The extension connects strictly to 127.0.0.1:9876. No external connections are made.

• Prompt Safety Rule: Agents are instructed never to click final payment or checkout confirmation buttons without explicit user consent.

📄 License

MIT License © 2026 Kadir Berk Polat