gasoline-mcp

Browser observability for AI coding agents - autonomously debug and fix issues in real time. Streams console logs, network errors, and exceptions to Claude Code, Copilot, Cursor, or any MCP-compatible assistant. Enterprise ready.

Documentation • Quick Start • Features • MCP Setup

Quick Start

Option A: NPM (recommended)

# 1. Clone the repo for the extension
git clone https://github.com/brennhill/gasoline-mcp-ai-devtools.git
cd gasoline

# 2. Load the extension:
#    - Open chrome://extensions
#    - Enable Developer mode
#    - Click "Load unpacked" and select the `extension/` folder from this repo

# 3. The server will start automatically when your AI tool connects via MCP
#    (no manual start needed - see MCP config below)

Option B: PyPI (Python)

# 1. Clone the repo for the extension
git clone https://github.com/brennhill/gasoline-mcp-ai-devtools.git
cd gasoline

# 2. Load the extension:
#    - Open chrome://extensions
#    - Enable Developer mode
#    - Click "Load unpacked" and select the `extension/` folder from this repo

# 3. The server will start automatically when your AI tool connects via MCP
#    (no manual start needed - see MCP config below)

Option C: From source (requires Go 1.21+)

# 1. Clone the repo
git clone https://github.com/brennhill/gasoline-mcp-ai-devtools.git
cd gasoline

# 2. Start the server
go run ./cmd/dev-console

# 3. Load the extension manually:
#    - Open chrome://extensions
#    - Enable Developer mode
#    - Click "Load unpacked" and select the `extension/` folder in this repo

Verify setup:

curl http://localhost:7890/health
# Should return: {"status":"ok","version":"5.0.0",...}

MCP config (add to your .mcp.json or Claude Code settings):

Option A: NPM

{
  "mcpServers": {
    "gasoline": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "gasoline-mcp", "--port", "7890", "--persist"]
    }
  }
}

Option B: PyPI

{
  "mcpServers": {
    "gasoline": {
      "type": "stdio",
      "command": "gasoline-mcp",
      "args": ["--port", "7890", "--persist"]
    }
  }
}

Architecture: The MCP system spawns a single Gasoline process that runs both:

• HTTP server on port 7890 (for browser extension)
• stdio MCP protocol (for AI tool)

Both interfaces share the same browser telemetry state. Do NOT manually start Gasoline — let the MCP system manage the process lifecycle.

Option C: Local development (must run from repo root)

{
  "mcpServers": {
    "gasoline": {
      "type": "stdio",
      "command": "go",
      "args": ["run", "./cmd/dev-console", "--port", "7890", "--persist"]
    }
  }
}

Works with Claude Code, Cursor, Windsurf, Claude Desktop, Zed, and any MCP-compatible tool.

Full setup guide →

CLI options:

Comparison

🟡 = Coming in v6.0 — See roadmap

Why You Cook With Gasoline

No debug port required. Other tools need Chrome launched with --remote-debugging-port, which disables security sandboxing and breaks your normal browser workflow. Gasoline uses a standard extension — your browser stays secure and unmodified.

Single binary, zero runtime. No Node.js, no Python, no Puppeteer, no package.json. One Go binary that runs anywhere. No supply chain risk. No node_modules.

Captures what others can't. WebSocket messages, full request/response bodies, user action recording, Web Vitals, automatic regression detection, API schema inference, and Playwright test generation from real browser sessions — features no other MCP browser tool offers.

Works with every MCP tool. Claude Code, Cursor, Windsurf, Zed, Claude Desktop, VS Code + Continue. Switch AI tools without changing your debugging setup.

Enterprise-safe by design. Binds to 127.0.0.1 only. Auth headers are stripped automatically. No telemetry, no accounts, no cloud. Audit the source — it's AGPL-3.0.

What It Does

• Console logs — console.log(), .warn(), .error() with full arguments
• Network errors — Failed API calls (4xx, 5xx) with response bodies
• Exceptions — Uncaught errors with full stack traces
• WebSocket events — Connection lifecycle and message payloads
• Network bodies — Request/response payloads for API debugging
• User actions — Click, type, navigate, scroll recording with smart selectors
• Web Vitals — LCP, CLS, INP, FCP with regression detection
• Live DOM queries — Query the page with CSS selectors via MCP
• Accessibility audits — WCAG checks with SARIF export
• API schema inference — Auto-discover OpenAPI from captured traffic
• Session checkpoints — Save state, diff changes, detect regressions
• Test generation — Playwright tests and reproduction scripts from actions
• Noise filtering — Auto-detect and dismiss irrelevant errors
• Developer API — window.__gasoline.annotate() for custom context

Full feature list →

Privacy

100% local. No cloud, no analytics, no telemetry. Logs never leave your machine.

Privacy details →

Performance

See latest benchmarks for current performance data.

Last benchmarked: 2026-01-28 on darwin/arm64 (v5.1.0)

Known Issues

See KNOWN-ISSUES.md for current known issues and the v5.2 roadmap.

Development

make test                              # Go server tests
node --test tests/extension/*.test.js  # Extension tests
make dev                               # Build for current platform

Release process & quality gates → · Changelog →

License

AGPL-3.0 — Free for personal and internal company use. Commercial licensing available for proprietary integration.

cookwithgasoline.com

Pouring fuel on the AI development fire

If you find Gasoline useful, please consider giving it a star!