Skip to main content
Glama
tznthou

Simple Console MCP

by tznthou
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

simple-console-mcp

License: Apache 2.0 npm Node.js 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 = 'test@example.com' // 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: 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

License: Apache 2.0

This project is licensed under the Apache License 2.0.

Author

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tznthou/simple-console-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server