claude-code

How to Debug Browser Errors with Claude Code Using MCP

Jan 24, 2025

Brenn Hill

Claude Code is powerful, but it has a blind spot: it can’t see your browser. When your frontend throws an error, you open DevTools, find the relevant console message, copy it, switch to your terminal, paste it, and hope you grabbed enough context. This is slow, lossy, and breaks your flow.

Gasoline MCP is an open-source browser extension + MCP server that streams real-time browser telemetry (console logs, network errors, exceptions, WebSocket events) to AI coding assistants like Claude Code, Cursor, Windsurf, and Zed. It closes the feedback loop between browser and AI — automatically.

The Problem: Manual Copy-Paste Debugging

Without browser access, Claude Code operates on incomplete information. A typical debugging cycle looks like this:

You make a code change
You reload the browser
Something breaks
You open DevTools, scroll through console output
You copy the error, maybe the stack trace
You paste it into Claude Code
Claude asks a follow-up — back to DevTools

You lose context at every step. Stack traces get truncated. Network errors get missed entirely. You never think to check the WebSocket connection that silently dropped.

How Gasoline Solves This

Gasoline connects your browser directly to Claude Code via MCP (Model Context Protocol). Once connected, Claude Code can:

Read console logs — errors, warnings, and info messages with full stack traces
See network failures — failed API calls with status codes, URLs, and timing
Inspect request/response bodies — see exactly what your API returned
Monitor WebSocket events — catch dropped connections and malformed frames
Query the DOM — inspect element state with CSS selectors
Generate Playwright tests — turn a real browser session into a reproducible test

Instead of you copying errors to Claude, Claude pulls what it needs directly.

How Do I Connect Claude Code to My Browser?

Setup takes under 60 seconds.

Step 1: Start the server

npx gasoline-mcp@latest

Single Go binary. No Node.js runtime. No node_modules/. Zero dependencies.

Step 2: Install the Chrome extension

Grab it from the Chrome Web Store (search “Gasoline”). The toolbar icon shows Connected when the server is running.

Step 3: Add the MCP config

Add this to .mcp.json in your project root:

{
  "mcpServers": {
    "gasoline": {
      "command": "npx",
      "args": ["-y", "gasoline-mcp@latest"]
    }
  }
}

Restart Claude Code. The server starts automatically on every session.

Step 4: Ask Claude

Open your web app in Chrome and ask:

“What errors are in the browser?”

Claude Code calls Gasoline’s observe tool and gets back structured data — not a screenshot, not a blob of text, but parsed console entries with timestamps, levels, stack traces, and source locations.

What Browser Data Can Claude Code See Through Gasoline MCP?

Gasoline exposes five composite tools to Claude Code:

Tool	What Claude Can Do
`observe`	Read console errors, network requests, WebSocket events, Web Vitals, page info
`analyze`	Detect performance regressions, audit accessibility, diff sessions
`generate`	Create Playwright tests, reproduction scripts, HAR exports
`configure`	Filter noise, manage log levels, set persistent memory
`query_dom`	Inspect live DOM state using CSS selectors

When Claude calls observe with what: "errors", it gets back every console error from the active tab — structured, timestamped, and ready to act on. When it calls observe with what: "network", it sees every failed HTTP request with status codes, URLs, headers, and optionally full response bodies.

This is not a one-shot snapshot. Gasoline streams continuously. Claude sees errors the moment they happen.

What About Privacy?

Gasoline runs entirely on localhost. The server binary binds to 127.0.0.1 only, rejects non-localhost connections at the TCP level, and never makes outbound network calls. Authorization headers are stripped by default. Request/response body capture is opt-in.

No data leaves your machine. No accounts. No telemetry.

Get Started

npx gasoline-mcp@latest

One command. Zero dependencies. Claude Code sees your browser in under a minute.

Full setup guide