simple-console-mcp

← Back to Muripo HQ

Minimal Console MCP — The smallest unit for browser debugging

中文版 (Chinese)

TL;DR

An extremely minimal MCP Server focused on browser Console Log monitoring. 97% lighter than chrome-devtools-mcp (4 tools vs 50+), so your AI assistant won't consume a ton of context tokens while debugging.

| Comparison | chrome-devtools-mcp | simple-console-mcp | |------------|---------------------|-------------------| | Tools | 50+ | 4 | | Context Cost | ~5000 tokens | ~200 tokens | | Focus | Full-featured | Console + JS execution |

Why I Built This

This project started with a simple question: "I just want to see Console Logs. Why do I need 50 tools?"

chrome-devtools-mcp is powerful, but every time the AI calls a tool, it needs to understand all 50+ tools first. The tool descriptions alone consume a huge amount of context. For scenarios where you just want to quickly debug JavaScript errors, that's wasteful.

So I built this "Minimum Viable MCP":

• list_targets — List browser tabs
• get_console_logs — Read Console output
• navigate — Navigate or reload
• execute_js — Execute JavaScript in page context

Just four tools. Good enough.

The core goal of this MCP is to fully embrace the subtraction principle — achieve maximum effect with minimum functionality. It's also an application of the 80/20 rule: if 80% of debugging scenarios only need Console Logs, why load 100% of the tools?

Test Verification

All features have been tested with a comprehensive test suite:

Test Scenarios

| Test | Description | Status | |------|-------------|--------| | 01-basic-logs | console.log, warn, error, info, debug | ✅ Pass | | 02-js-errors | TypeError, ReferenceError, SyntaxError, RangeError | ✅ Pass | | 03-async-errors | Promise rejection, async/await, setTimeout, fetch errors | ✅ Pass | | 04-stress-test | 600 logs generated, verifies 500 limit works | ✅ Pass | | 05-special-chars | Emoji, Chinese, Japanese, JSON objects, Unicode | ✅ Pass |

Feature Verification

| Feature | Status | |---------|--------| | list_targets - List browser tabs | ✅ | | get_console_logs - Read console output | ✅ | | navigate - Navigate or reload page | ✅ | | execute_js - Execute JavaScript in page | ✅ | | filter parameter - Filter log types | ✅ | | Auto-launch Chrome with debug mode | ✅ | | Isolated user-data-dir (/tmp/chrome-cdp-9222) | ✅ | | 500 log cache limit | ✅ | | 5s execution timeout for execute_js | ✅ | | Clear error message for Chrome conflicts | ✅ |

Sample Test Output

$ list_targets
Available targets:
[0] page: http://127.0.0.1:5500/test/01-basic-logs.html

$ get_console_logs
=== Console Logs for http://127.0.0.1:5500/test/01-basic-logs.html ===
[2025-12-17T15:21:28.054Z] LOG: [Test 01] Page loaded - Basic Logs Test
[2025-12-17T15:21:28.054Z] LOG: This is a LOG message
[2025-12-17T15:21:28.054Z] WARN: This is a WARNING message
[2025-12-17T15:21:28.054Z] ERROR: This is an ERROR message
[2025-12-17T15:21:28.054Z] INFO: This is an INFO message
[2025-12-17T15:21:28.054Z] DEBUG: This is a DEBUG message
(showing 6 of 6 total, filter: all)

$ execute_js --code="document.title"
=== JavaScript Executed ===
Code: document.title

Result:
"Test 01: Basic Console Logs"

Installation

Option 1: npm (Recommended)

Claude Code (one-liner):

claude mcp add simple-console -- npx -y simple-console-mcp

Claude Desktop or other MCP clients (Cursor / Windsurf / Cline):

{
  "mcpServers": {
    "simple-console": {
      "command": "npx",
      "args": ["-y", "simple-console-mcp"]
    }
  }
}

Option 2: GitHub URL

Claude Code:

claude mcp add simple-console -- npx -y github:tznthou/simple-console-mcp

Option 3: Local Installation

git clone https://github.com/tznthou/simple-console-mcp.git
cd simple-console-mcp && npm install

claude mcp add simple-console -- node /path/to/simple-console-mcp/src/index.js

Starting Chrome CDP

Auto-launch (v1.1.0+)

No manual setup required! The MCP automatically detects whether Chrome has CDP enabled:

• If CDP is already enabled → connects directly
• If not → auto-launches a new Chrome with debug mode using isolated profile

Just install the MCP, and tell Claude "help me debug" — it handles everything automatically.

Note (v1.4.0+): If you already have a regular Chrome open, the MCP will show a clear error message asking you to close it first. This prevents conflicts between regular and debug Chrome instances.

Manual Start (Fallback)

If auto-launch fails, you can start Chrome manually:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

Tools

list_targets

List all available browser targets (pages, Service Workers, etc.).

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | port | number | 9222 | Chrome CDP port |

Available targets:
[0] page: http://localhost:3000
[1] service_worker: chrome-extension://xxx/background.js
[2] page: chrome-extension://xxx/popup.html

get_console_logs

Get Console output from a specific target. Starts monitoring on first call.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | targetIndex | number | 0 | Target index from list_targets | | maxLines | number | 50 | Maximum lines to return | | filter | string | "all" | Filter type: all / error / warn / log / info / debug | | port | number | 9222 | Chrome CDP port |

=== Console Logs for http://localhost:3000 ===
[12:34:56] ERROR: Uncaught TypeError: Cannot read property 'x' of undefined
[12:34:57] WARN: Deprecation warning...
(showing 2 of 50 total logs, filter: all)

navigate

Navigate to a URL or reload the page.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | url | string | - | Target URL or "reload" | | targetIndex | number | 0 | Target index | | port | number | 9222 | Chrome CDP port |

Navigated to: http://localhost:3000/login
Page title: "Login"
(Console logs cleared)

execute_js (New in v1.4.0)

Execute JavaScript code in the page context. Useful for clicking buttons, filling forms, reading DOM, or calling page functions.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | code | string | - | JavaScript code to execute (max 10,000 chars) | | targetIndex | number | 0 | Target index | | port | number | 9222 | Chrome CDP port |

Safety measures:

• Code length limit: 10,000 characters
• Execution timeout: 5 seconds
• Result size limit: 50,000 characters

Examples:

// Click a button
document.querySelector('button#submit').click()

// Read page title
document.title

// Call page function
myApp.doSomething()

// Fill form input
document.getElementById('email').value = '[email protected]'

// Get element count
document.querySelectorAll('.item').length

=== JavaScript Executed ===
Code: document.title

Result:
"My Application"

Architecture

graph TB
    subgraph Client["AI Client"]
        CLAUDE["Claude Desktop<br/>or Claude Code"]
    end

    subgraph MCP["simple-console-mcp"]
        SERVER["MCP Server<br/>StdioTransport"]
        TOOLS["4 Tools<br/>list_targets | get_console_logs | navigate | execute_js"]
        CACHE["Log Cache<br/>Map + WeakMap"]
    end

    subgraph Browser["Chrome Browser"]
        CDP["CDP Port 9222<br/>--remote-debugging-port"]
        PAGES["Browser Targets<br/>Pages | Service Workers"]
        CONSOLE["Console Events<br/>log | error | warn"]
    end

    CLAUDE --> |"MCP Protocol"| SERVER
    SERVER --> TOOLS
    TOOLS --> |"puppeteer-core"| CDP
    CDP --> PAGES
    PAGES --> |"console event"| CACHE
    CACHE --> |"formatted logs"| TOOLS

How It Works: Pull-based

Claude calls get_console_logs → MCP returns accumulated logs → Claude processes
         ↑                                                        |
         └──────────────── Claude must call again ────────────────┘

Behavior:

1. On first get_console_logs call, MCP starts monitoring that target
2. Console events are continuously collected in memory (max 500 entries)
3. Claude does NOT receive automatic notifications — must call get_console_logs again to see new logs

Why Pull-based? MCP protocol is request-response based and doesn't support push notifications. The server cannot proactively tell Claude "there's a new error" — Claude must actively ask.

Chrome Extension Development

This MCP supports monitoring Console output from Chrome Extensions:

[0] page: http://localhost:3000           ← Regular webpage
[1] service_worker: chrome-extension://abc/background.js  ← Extension background script
[2] page: chrome-extension://abc/popup.html               ← Extension popup

Use different targetIndex values to monitor each target separately.

Tech Stack

| Technology | Purpose | |------------|---------| | Node.js 18+ | Runtime | | ES Modules | Module system | | @modelcontextprotocol/sdk | MCP protocol implementation | | puppeteer-core | Chrome CDP connection (no bundled Chromium) | | zod | Parameter validation |

Project Structure

simple-console-mcp/
├── src/
│   └── index.js        # MCP Server main code (~550 lines, security hardened)
├── bin/
│   └── start-chrome.sh # Chrome startup script
├── package.json
├── README.md           # English docs (this file)
├── README_ZH.md        # Chinese docs
└── LICENSE             # Apache-2.0

Requirements

| Item | Requirement | |------|-------------| | Node.js | 18+ | | Chrome | Any version with --remote-debugging-port enabled | | OS | macOS / Linux / Windows |

Notes

1. Chrome must have CDP enabled: Chrome without --remote-debugging-port cannot be connected
2. One Chrome at a time: If multiple Chrome instances exist, MCP connects to the first one
3. Log cache limit: Each target keeps at most 500 logs, older ones are automatically removed
4. Navigation clears logs: Calling navigate clears the target's log cache

Changelog

v1.4.0 (2025-12-17)

New Features:

• ✨ execute_js tool: Execute JavaScript in page context
  • Click buttons, fill forms, read DOM, call page functions
  • Safety measures: 5s timeout, 10K code limit, 50K result limit
• ✨ Simplified Chrome launch logic:
  • Directly launches debug Chrome with isolated profile (/tmp/chrome-cdp-9222)
  • Clear error message when regular Chrome conflicts with debug Chrome

Improvements:

• 📦 Code grew from ~460 to ~550 lines (+20%)
• 🔧 Removed automatic Chrome kill logic (user must close regular Chrome manually)
• 📝 Better error messages explaining Chrome conflict resolution

v1.3.6 (2025-12-17)

Security Hardening (comprehensive code review fixes):

| Issue | Severity | Fix | |-------|----------|-----| | URL Protocol Injection | 🔴 Critical | Added validateUrl() allowing only http:// and https:// | | Shell Command Injection | 🔴 Critical | start-chrome.sh validates port must be integer 1024-65535 | | Cleanup Race Condition | 🔴 Critical | Added isCleaningUp flag, uncaughtException handler | | Private API Dependency | 🟠 High | getTargetId() prefers official API, falls back to _targetId | | Incomplete Resource Cleanup | 🟠 High | Added browser.isConnected() check before disconnect | | Missing HTTP Warning | 🟡 Medium | Non-localhost HTTP URLs now show security warning | | Unlimited URL Length | 🟡 Medium | Added MAX_URL_LENGTH = 2048 limit |

v1.3.1 (2025-12-13)

• 🐛 Fixed navigate tool's targetIndex inconsistency with list_targets

v1.3.0 (2025-12-13)

Security Fixes:

| Issue | Severity | Fix | |-------|----------|-----| | Command Injection | 🔴 Critical | Added validatePort() | | Race Condition | 🔴 Critical | Used Promise lock | | Resource Leak | 🔴 Critical | Added SIGINT/SIGTERM handlers |

v1.2.0 (2025-12-12)

• 🔧 Auto-launched Chrome now uses isolated user-data-dir

v1.1.0 (2025-12-12)

• ✨ Added auto-launch Chrome CDP feature

v1.0.0 (2025-12-12)

• 🎉 Initial release

License

This project is licensed under the Apache License 2.0.

Author

• GitHub: @tznthou