browser-runtime-mcp 0.1.0

MCP server that gives AI agents real-time access to browser runtime errors, console logs, and page diagnostics via a Chrome Extension.

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

Browse any website. Ask your AI agent:

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

MCP Tools

Tool	Description
get_browser_errors	Runtime errors with stack traces and DOM context
get_console_logs	Console output (error/warn/log), filterable by level
get_page_info	Tracked pages and buffer statistics
clear_buffers	Clear all buffered data for a fresh start

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.

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