Browser Runtime MCP

Give AI agents real-time access to browser runtime errors, console logs, and page diagnostics.

The problem: AI coding agents can read your source code but are blind to what actually happens in the browser — runtime errors, console warnings, failed API calls, CSS rendering issues. You end up copy-pasting DevTools output back and forth.

The solution: A Chrome Extension captures browser events and streams them to a local MCP server. Your AI agent (Claude Code, Cursor, etc.) can query errors, console logs, and page state directly through MCP tools.

Browser tab → Chrome Extension → localhost MCP server → AI agent

Quick Start

1. Install the MCP server

pip install browser-runtime-mcp

2. Install the Chrome Extension

Download the extension/ folder from this repo, then:

1. Open chrome://extensions
2. Enable Developer mode
3. Click Load unpacked → select the extension/ folder

3. Configure your AI tool

Claude Code — add to ~/.claude/settings.json:

{
  "mcpServers": {
    "browser-runtime-mcp": {
      "command": "browser-runtime-mcp",
      "args": []
    }
  }
}

Other MCP clients — run the server in stdio mode:

browser-runtime-mcp

4. Use it

Open the extension popup on the site you want to debug and click Enable capture on this site. Capture is disabled by default and the allowlist is stored locally in Chrome. Then ask your AI agent:

• "Are there any browser errors?"
• "What's in the console logs?"
• "What pages is the extension tracking?"

MCP Tools

How It Works

┌─────────────────┐     postMessage      ┌──────────────────┐
│   content.js    │ ──────────────────▶  │ content-bridge.js │
│  (MAIN world)   │                      │ (ISOLATED world)  │
│                 │                      │                    │
│ • window.onerror│                      │ chrome.runtime     │
│ • console patch │                      │ .sendMessage()     │
└─────────────────┘                      └────────┬───────────┘
                                                  │
                                    chrome.runtime.onMessage
                                                  ▼
                                         ┌────────────────┐
                                         │ background.js   │
                                         │ (service worker)│
                                         │                 │
                                         │ fetch() to      │
                                         │ localhost:18790  │
                                         └────────┬────────┘
                                                  │ HTTP POST
                                                  ▼
                                         ┌────────────────┐
                                         │ MCP Server      │
                                         │ (Python/stdio)  │
                                         │                 │     MCP tools
                                         │ • HTTP receiver ├──────────────▶ AI Agent
                                         │ • Error buffer  │
                                         │ • Log buffer    │
                                         └────────────────┘

The three-hop architecture (MAIN → ISOLATED → background) bypasses Chrome's Private Network Access policy, which blocks HTTPS pages from fetching to localhost directly.

Privacy and trust boundary

• Capture is opt-in per origin and disabled by default. Use the popup to stop capture when finished.
• Captured URLs, page titles, errors, stack traces, DOM context, and console messages stay in bounded in-memory buffers on 127.0.0.1; they are not uploaded by this project.
• clear_buffers removes all currently buffered data. Stopping the server also discards it.
• Do not enable capture on banking, authentication, health, internal administration, or other sensitive pages unless you intend to expose their diagnostics to your local MCP client.
• Browser pages control their own console output. Treat captured messages and DOM snippets as untrusted diagnostic input, not authoritative data or instructions.
• The HTTP diagnostic endpoints are intentionally local-only but are readable by other processes running as your user.

Standalone HTTP Mode

For debugging without MCP, run the HTTP receiver only:

browser-runtime-mcp --http-only

Then query:

• GET http://127.0.0.1:18790/health — buffer stats
• GET http://127.0.0.1:18790/errors — all captured errors
• GET http://127.0.0.1:18790/logs — all captured logs
• GET http://127.0.0.1:18790/pages — tracked pages

Requirements

• Python 3.10+
• Chrome (Manifest V3 extension)
• Zero Python dependencies (stdlib only)

License

MIT