console-bridge

<div align="center">

<img src="packages/extension/icon.png" alt="console-bridge icon" width="128" height="128">

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

</div>

---

Why console-bridge?

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.

| | console-bridge | Browser automation tools | |--|---------------|--------------------------| | Capture mode | Passive, always on | On-demand, explicit connect | | Tab coverage | All tabs simultaneously | Single tab at a time | | Log storage | 10K logs with TTL | None | | Search | Regex, keywords, time range | Not supported | | Skills | Custom debugging skills (.md) | Generic page access | | Use case | Debugging | UI automation |

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

---

Quick Start

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

1. Install MCP Server

Standard config (works with most MCP clients):

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

<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor" height="32">

<details> <summary>Claude Code</summary>

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

Or add to ~/.claude.json:

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

</details>

<details> <summary>VS Code</summary>

Add to your VS Code settings or use the CLI:

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

</details>

<details> <summary>Windsurf</summary>

Follow Windsurf MCP documentation. Use the standard config above.

</details>

<details> <summary>Other clients</summary>

Add the standard config to your MCP configuration file. See MCP documentation for client-specific instructions.

</details>

2. Install Browser Extension

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"

3. Verify Installation

Restart your MCP client, then try:

Show me recent console errors

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

---

Features

Log Capture & Analysis

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

Powerful Search

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

Smart Tab Suggestions

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

Suggest which tab is my Next.js app

Session Scoping

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

Show errors from current session only

JS Execution & DOM Queries

Run JavaScript in page context or query DOM elements directly.

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

One-Click Cursor Integration

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

🧠 Project Skills (Context for AI)

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: ```markdown --- 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 ```

---

MCP Tools

| Tool | Purpose | |------|---------| | console_tabs | List all tabs or get smart suggestions based on project context | | console_logs | List, get single log, or tail with filtering (level, tab, URL, time) | | console_search | Regex or keyword search with context lines and exclusions | | console_snapshot | Quick summary of recent errors, warnings, and patterns | | console_browser_execute | Run JavaScript in page context | | console_browser_query | Query DOM elements by CSS selector | | console_skills_list | List project-specific debugging playbooks | | console_skills_load | Load a specific debugging skill |

---

Configuration

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)

---

Architecture

┌─────────────────┐     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

---

Development

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

Project Structure

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

---

License

MIT