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

---
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