# 🌐 Zen Browser MCP

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Runtime: Bun](https://img.shields.io/badge/Runtime-Bun-f472b6.svg)](https://bun.sh)
[![Protocol: MCP](https://img.shields.io/badge/Protocol-MCP%202024--11--05-green.svg)](https://modelcontextprotocol.io)
[![Browser: Zen / Firefox](https://img.shields.io/badge/Browser-Zen%20%2F%20Firefox-orange.svg)](https://zen-browser.app)

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.

---

## 🏗️ Architecture

```text
┌───────────────────────────┐
│ 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

```bash
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:

```bash
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:
   ```text
   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:

```bash
zen-agent status
```

You should see:
```text
✅ 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:

```bash
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`):

```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:

| Tool | Parameters | Description |
|---|---|---|
| `zen_status` | *(none)* | Returns connection status, current tab title, and active URL. |
| `zen_goto` | `url: string` | Navigates the active Zen tab to the specified URL. |
| `zen_inspect` | *(none)* | Scans visible buttons, links, search inputs, and returns numbered `#id` list. |
| `zen_click` | `target: string \| number` | Highlights and clicks an element by `#id`, button text, or CSS selector. |
| `zen_type` | `target`, `text`, `enter?` | Focuses an input, types text, and optionally triggers Enter/submit. |
| `zen_scroll` | `direction?`, `amount?` | Smoothly scrolls the active page (`up` or `down`). |
| `zen_eval` | `code: string` | Runs custom JavaScript in the page context and returns the result. |

---

## 💻 Standalone CLI Usage (`zen-agent`)

You can also control Zen Browser directly from your terminal:

```bash
# 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:
```bash
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](https://github.com/KadirBerkpolat1)