Gasoline MCP is an AI Debugger, Inspector, and Observability toolkit. It acts as Chrome DevTools for AI Agents using the Model Context Protocol (MCP).
npm install gasoline-mcpBrowser 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.
MCP (Model Context Protocol) lets your AI assistant talk to external tools. You just need to add a config snippet — no global install required. npx downloads and runs the binary automatically.
Pick your tool and add the config:
Claude Code (CLI)
Option A: Per-project (recommended for teams) — create .mcp.json in your project root:
``json`
{
"mcpServers": {
"gasoline": {
"type": "stdio",
"command": "npx",
"args": ["-y", "gasoline-mcp", "--port", "7890", "--persist"]
}
}
}
Option B: Global — add to ~/.claude/settings.json:
`json`
{
"mcpServers": {
"gasoline": {
"type": "stdio",
"command": "npx",
"args": ["-y", "gasoline-mcp", "--port", "7890", "--persist"]
}
}
}
After adding, restart Claude Code. You should see "gasoline" listed when you run /mcp.
Architecture note: Your AI tool spawns a SINGLE Gasoline process that handles both:
- HTTP server on port 7890 (for browser extension telemetry)
- stdio MCP protocol (for AI tool commands)
Both interfaces share the same browser state. Do NOT manually start Gasoline — let the MCP system manage it.
Claude Desktop
Edit your config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
`json`
{
"mcpServers": {
"gasoline": {
"type": "stdio",
"command": "npx",
"args": ["-y", "gasoline-mcp", "--port", "7890", "--persist"]
}
}
}
Restart Claude Desktop after saving.
Cursor
Go to Settings → MCP Servers → Add Server, or add to ~/.cursor/mcp.json:
`json`
{
"mcpServers": {
"gasoline": {
"type": "stdio",
"command": "npx",
"args": ["-y", "gasoline-mcp", "--port", "7890", "--persist"]
}
}
}
Restart Cursor after saving.
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
`json`
{
"mcpServers": {
"gasoline": {
"type": "stdio",
"command": "npx",
"args": ["-y", "gasoline-mcp", "--port", "7890", "--persist"]
}
}
}
Restart Windsurf after saving.
VS Code with Continue
Add to ~/.continue/config.json:
`json`
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "npx",
"args": ["-y", "gasoline-mcp", "--port", "7890", "--persist"]
}
}
]
}
}
Zed
Add to ~/.config/zed/settings.json:
`json`
{
"context_servers": {
"gasoline": {
"command": {
"path": "npx",
"args": ["-y", "gasoline-mcp", "--port", "7890", "--persist"]
}
}
}
}
The extension captures logs from your browser and sends them to the local Gasoline server.
1. Download or clone the Gasoline repository
2. Open chrome://extensions in Chromeextension/
3. Enable Developer mode (top right toggle)
4. Click Load unpacked
5. Select the folder from the repository
Once installed, you'll see the Gasoline icon in your browser toolbar. Click it to check connection status.
Your AI assistant now has access to 5 composite tools:
| Tool | What it does |
| ---- | ------------ |
| observe | Real-time browser state (errors, logs, network, websocket, actions, vitals, page) |analyze
| | Data analysis and insights (performance, api, accessibility, changes, timeline) |generate
| | Code generation from captured data (reproduction, test, pr_summary, sarif, har) |configure
| | Session and noise management (store, noise_rule, dismiss, clear) |query_dom
| | Live DOM inspection via CSS selectors |
Try it: open your web app, trigger an error, then ask your AI assistant _"What browser errors do you see?"_
`
Browser → Extension → Local Server (localhost:7890) → Log File → AI reads via MCP
1. The extension captures console logs, network errors, and exceptions from your browser
2. Logs are sent to the Gasoline server running on your machine (localhost only)
3. Your AI assistant reads the logs through the MCP protocol
4. Everything stays local — no data ever leaves your machine
If your AI tool doesn't support MCP, you can run the server standalone:
`bash`
npx gasoline-mcp
This starts an HTTP server on http://localhost:7890 and writes logs to ~/gasoline-logs.jsonl. Your AI can read this file directly.
`
gasoline-mcp [options]
--port
--log-file
--max-entries
--mcp No-op (MCP mode is the default)
--version Show version
--help Show help
`
"gasoline" not showing up in my AI tool?
- Make sure you restarted the AI tool after adding the config
- Check the config file path is correct for your tool
- Try running npx gasoline-mcp --version to verify the package works
"bind: address already in use" error?
If MCP fails to start with a port conflict, you likely have a manually-started Gasoline instance running:
`bashFind and kill the conflicting process
ps aux | grep gasoline | grep -v grep
kill
Then reload your MCP connection. The MCP system will spawn a fresh instance. Remember: do NOT manually start Gasoline when using MCP mode.
Extension shows "Disconnected"?
- The MCP server starts automatically when your AI tool launches — check if it's running:
- Verify the extension's Server URL matches your config (default: )
- Try restarting your AI tool to re-initialize the MCP connectionNo logs appearing?
- Click the extension icon and check the capture level (try "All Logs")
- Make sure the page was loaded/refreshed after the extension was installed
- Check
~/gasoline-logs.jsonl to see if entries are being writtenSupported Platforms
- macOS (Apple Silicon & Intel)
- Linux (x64 & ARM64)
- Windows (x64)
Privacy
100% local. Logs never leave your machine. No cloud, no analytics, no telemetry. The server only binds to
127.0.0.1`.