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?

	Eyebrowse	Playwright/Puppeteer MCP	Headless agents
Browser	Your real Chrome	Hidden headless browser	Hidden headless browser
Session	Shared -- your cookies, logins, state	Isolated -- starts fresh	Isolated
Visibility	You see everything the AI does	Invisible	Invisible
Interaction	AI and human use the same window	AI only	AI only
Setup	Extension + daemon	npm package	Varies

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

Tool	Description
look	Screenshot + page URL/title. Optionally include the accessibility tree.
screenshot	Capture a screenshot of the current page. Supports full-page and quality settings.
get_page_info	Get current page URL and title. Optionally include the accessibility tree.
browser_status	Check connection health and paired window info.
list_windows	List all Chrome windows.
pair_window	Pair with a Chrome window by its window ID.
unpair	Release the currently paired Chrome window.
open_browser	Open a new Chrome window at the given URL. Auto-pairs to the session.
click	Click an element by CSS selector, visible text, or x/y coordinates.
type	Type text into an element. Supports clearing, pressing Enter, and keystroke delay.
scroll	Scroll the page by direction/amount, to an edge, or scroll an element into view.
navigate	Navigate to a URL, or go back/forward/reload.
highlight	Highlight elements matching a CSS selector with a configurable color.
annotate	Add a callout annotation near an element.
show_message	Show a toast notification in the browser.
clear_overlays	Remove all highlights and annotations from the page.
list_tabs	List all tabs in the paired Chrome window.
switch_tab	Switch to a specific tab by its tab ID.
close_window	Close the paired window or a specific window by ID.
evaluate	Execute a JavaScript expression in the page and return the result. Use for bulk DOM data extraction.
print_to_pdf	Export the current page as a PDF file. Returns the file path.

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