Eyebrowse

Give your AI agent eyes and hands in the browser.

Eyebrowse is an MCP server that connects AI coding agents to real Chrome browsers. Not headless. Not isolated. Your browser, your session, AI-assisted.

What is Eyebrowse?

Eyebrowse bridges AI agents and Chrome through the Model Context Protocol (MCP). Your AI sees screenshots, reads page structure via accessibility trees, and interacts with pages -- clicking, typing, scrolling, navigating -- all in a real Chrome window you can watch and use alongside it.

Unlike headless browser tools, Eyebrowse operates in your actual browser. Same cookies, same logins, same tabs. The AI is a copilot in your browser, not a robot in a hidden one.

Why Eyebrowse?

Use Cases

• Web scraping -- "Search for X on these 5 sites, extract prices and links" (supports parallel workers with separate windows)

• QA review -- "Look at this page and tell me what's broken"

• Form filling -- "Fill out this application with these details"

• Research -- "Find recent articles about Y, summarize the top 3"

• Page capture -- "Save this page as a PDF" or "Take a screenshot of the dashboard"

• Debugging -- "Open localhost:3000, click the login button, tell me what happens"

• Monitoring -- watch a page for changes using your existing logged-in session

• Workflow automation -- automate repetitive browser tasks in your authenticated session

Features

• Screenshots -- capture visible tab or full-page screenshots as JPEG

• Accessibility tree -- read page structure via Chrome DevTools Protocol

• Click, type, scroll, navigate -- full browser interaction by CSS selector, text content, or coordinates

• Multi-window and multi-tab -- pair specific windows to sessions, list and switch tabs

• Highlights and annotations -- overlay elements with colored highlights, callout annotations, or toast messages

• Print to PDF -- export pages with configurable paper size, orientation, and page ranges

• Evaluate JavaScript -- run expressions in the page context and return structured data, ideal for bulk DOM extraction

• Auto-start daemon -- MCP server spawns the daemon automatically on first tool call

• Session isolation -- each Claude Code session registers independently with its own pairing

Quick Install

npx eyebrowse install

The installer checks prerequisites, configures Claude Code's MCP settings, and walks you through loading the Chrome extension. See Manual Setup if you prefer to do it yourself.

Manual Setup

1. Install Bun

curl -fsSL https://bun.sh/install | bash

2. Clone the repository

git clone https://github.com/evan108108/eyebrowse.git
cd eyebrowse

3. Install dependencies

bun install

4. Load the Chrome extension

1. Open chrome://extensions in Chrome

2. Enable Developer mode (top right)

3. Click Load unpacked

4. Select the extension/ directory from this repository

5. Add the MCP server to Claude Code

Add the following to ~/.claude.json (or your project's .mcp.json):

{
  "mcpServers": {
    "eyebrowse": {
      "command": "bun",
      "args": ["run", "/path/to/eyebrowse/mcp/index.ts"]
    }
  }
}

Replace /path/to/eyebrowse with the actual path where you cloned the repo.

Architecture

+-------------------+       WebSocket        +-------------------+       stdio/MCP       +-------------------+
|                   |  ws://localhost:7890/ws |                   |                       |                   |
|  Chrome Extension |<---------------------->|  Daemon (Bun)     |<--------------------->|  MCP Server       |
|  (Manifest V3)    |                        |  Port 7890        |   HTTP JSON API       |  (stdio transport)|
|                   |  events, bridge req/res|                   |                       |                   |
+-------------------+                        +-------------------+                       +-------------------+
        |                                            |                                           |
        v                                            v                                           v
  chrome.tabs API                             Session registry                            Claude Code
  chrome.debugger API                         Window pairing                              (MCP client)
  chrome.scripting API                        Auth token management
  Content script injection                    Rate limiting

Chrome Extension -- Manifest V3 service worker that connects to the daemon over WebSocket. Bridges Chrome APIs (tabs, debugger, scripting) to daemon requests. Handles screenshots, accessibility tree capture, page interactions, overlays, and PDF export. Maintains a persistent connection with keepalive pings and exponential backoff reconnection.

Daemon -- Bun HTTP + WebSocket server on port 7890. Routes tool calls from the MCP server to the extension, manages session registration, window pairing, and authentication. Runs a stale session reaper every 2 minutes.

MCP Server -- Thin MCP-protocol wrapper that exposes 21 tools over stdio. Communicates with the daemon via HTTP. Auto-starts the daemon if unreachable. Each instance registers as a session identified by the working directory name.

Available Tools

How It Works

1. Connect -- The Chrome extension opens a WebSocket connection to the daemon at ws://localhost:7890/ws. The daemon validates the origin is a chrome-extension:// URL.

2. Register -- When Claude Code starts a session, the MCP server registers with the daemon over HTTP, receiving a session ID and bearer token. If the daemon is not running, the MCP server spawns it automatically.

3. Pair -- A Chrome window is paired to the session, either from the extension popup or programmatically via open_browser or pair_window. Each window can only be paired to one session at a time.

4. Execute -- Claude Code calls MCP tools. The MCP server forwards them as HTTP requests to the daemon, which translates them into bridge requests over WebSocket to the extension. The extension executes them using Chrome APIs and returns results back through the same chain.

Security

Eyebrowse operates entirely locally. Your data never leaves your machine. No cloud services, no telemetry, no external connections.

• Local-only -- The daemon binds to localhost:7890. The extension connects only to ws://localhost:7890/ws.

• Token authentication -- The daemon generates a random UUID token on first run, stored at ~/.eyebrowse/daemon.token with 0600 permissions. All HTTP requests require this token as a Bearer header. Constant-time comparison prevents timing attacks.

• Origin validation -- WebSocket upgrades are rejected unless the origin starts with chrome-extension://.

• CDP allowlist -- Only four Chrome DevTools Protocol commands are permitted: Accessibility.getFullAXTree, Accessibility.getPartialAXTree, Page.printToPDF, and Runtime.evaluate.

• URL validation -- open_browser and navigate only accept http: and https: URLs.

• Rate limiting -- open_browser is limited to 3 calls per minute per session.

• Session isolation -- Each MCP server instance registers as a separate session with independent window pairing.

Development

Run the daemon

bun run daemon/index.ts

The daemon starts on http://localhost:7890. Logs go to stderr. A daemon token is created at ~/.eyebrowse/daemon.token on first run.

Run the MCP server (standalone)

bun run mcp/index.ts

The MCP server communicates over stdio. It will auto-start the daemon if it is not already running.

Optional: launchd (macOS auto-start)

A template plist is provided at com.eyebrowse.daemon.plist. Replace the placeholder paths (__BUN_PATH__, __EYEBROWSE_HOME__, __BUN_DIR__) and copy to ~/Library/LaunchAgents/ to have the daemon start at login.

License

MIT