console-bridge

Give your AI assistant access to browser console logs

Capture logs from all tabs, search errors, and equip your AI with project-specific debugging skills.

Quick Start · Features · Tools · Config

1. 🔌 Passive & Always-On No need to launch a special browser instance or connect to specific tabs. console-bridge captures everything in the background.

2. 🧠 Teachable (Project Skills) Define custom debugging workflows in Markdown. Your AI reads them to understand how to debug your specific application.

3. 🔍 Context Efficient Stop dumping massive log files. Search, filter, and fetch only the relevant lines to save tokens and reduce noise.

Best for: "My app is throwing errors, help me debug" workflows.

console-bridge requires two components: a browser extension (captures logs) and an MCP server (stores/queries logs).

Standard config (works with most MCP clients):

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

claude mcp add console-bridge -s user -- npx -y console-bridge-mcp@latest

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

code --add-mcp '{"name":"console-bridge","command":"npx","args":["-y","console-bridge-mcp@latest"]}'

1. Download console-bridge-ext-v*.zip from the latest release
2. Unzip to a permanent location (e.g., ~/.console-bridge-extension)
3. Open Chrome → chrome://extensions
4. Enable "Developer mode" (toggle in top right)
5. Click "Load unpacked" → select the unzipped folder
6. Click the extension icon → verify it shows "Connected"

Restart your MCP client, then try:

Show me recent console errors

If you see log data, you're all set!

Logs stream continuously from all browser tabs to the MCP server. Filter by level, tab, URL pattern, or time range.

Show error logs from the last 5 minutes
Show logs from localhost:3000
Tail logs from the current tab

Regex and keyword search with context lines, AND/OR logic, and exclusions.

Search for "failed" OR "error" excluding "expected"
Search for /api\/users\/\d+/ with 3 lines of context

AI-assisted tab ranking based on your project context — ports, domains, URL patterns.

Suggest which tab is my Next.js app

Focus on logs from the current navigation only, ignoring stale logs from before the last page refresh.

Show errors from current session only

Run JavaScript in page context or query DOM elements directly.

Execute: window.featureFlags.enableDebug = true
Query DOM for '.error-message' elements

Click "Open in Cursor" in the extension popup to instantly open Cursor with a context-aware prompt to analyze the current tab's logs.

Teach your AI assistant how to debug your specific project. Create a .console-bridge/ directory in your project root and add Markdown files with debugging playbooks.

Why use Skills?

• Onboard AI instantly: Define complex debugging flows once, use them forever.
• Share knowledge: Commit your debugging guides so every team member's AI assistant knows them.
• Context-aware: The AI discovers available skills automatically.

Example: Create .console-bridge/auth-debug.md:

---
title: Debug Authentication Flow
description: Steps to diagnose login failures
---
1. Filter logs for "AuthService"
2. Check network requests to /api/login
3. Verify JWT token in local storage

Usage:

List available debugging skills
Load the auth debugging skill

Environment variables:

CONSOLE_MCP_PORT=9847              # WebSocket port
CONSOLE_MCP_DISCOVERY_PORT=9846    # HTTP discovery port
CONSOLE_MCP_MAX_LOGS=10000         # Max logs in memory
CONSOLE_MCP_LOG_TTL_MINUTES=60     # Auto-cleanup (0 = disable)

┌─────────────────┐     WebSocket      ┌─────────────────┐      stdio       ┌─────────────────┐
│                 │    (port 9847)     │                 │                  │                 │
│  Browser Ext.   │ ─────────────────▶ │   MCP Server    │ ◀──────────────▶ │  AI Assistant   │
│  (all tabs)     │    log batches     │  (stores/query) │    MCP protocol  │ (Cursor/Claude) │
│                 │                    │                 │                  │                 │
└─────────────────┘                    └─────────────────┘                  └─────────────────┘
        │                                      │
        │ captures console.*                   │ in-memory storage
        │ intercepts errors                    │ filtering engine
        │ sanitizes credentials                │ search engine
        │                                      │

Data flow:

1. Extension content script intercepts console.log/warn/error/debug
2. Logs are batched (50 logs/100ms) and sent via WebSocket
3. Server stores logs in-memory with configurable TTL
4. MCP tools query and analyze logs on demand

npm install && npm run build
npm run dev:server    # Hot reload server
npm run dev:extension # Hot reload extension
npm test              # Run tests

packages/
├── server/          # MCP server + WebSocket receiver
├── extension/       # Chrome extension (content script + popup)
└── shared/          # Shared types and Zod schemas

MIT