debugger-mcp

An MCP server for runtime debugging. Coding agents inject HTTP log calls into any codebase, collect logs at runtime, and analyze them — without needing developer eyes on a terminal.

Useful when you can't see the app's logs directly: frontend apps, remote servers, mobile apps, or any environment where console.log output isn't visible to the AI agent.

How it works

1. The agent starts a local HTTP server and gets an endpoint URL
2. The agent injects temporary POST /log calls into your code (in whatever language it uses)
3. You run the buggy scenario
4. The agent reads the logs and diagnoses the issue
5. The agent fixes the bug and removes all temporary logging code

Installation

Prerequisites

• Node.js >= 18

Build from source

npm install
npm run build

Add to your MCP client

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "debugger-mcp": {
      "command": "node",
      "args": ["/path/to/debugger-mcp/build/index.js"]
    }
  }
}

Claude Code

claude mcp add debugger-mcp -- node /path/to/debugger-mcp/build/index.js

Or if installed globally via npm:

claude mcp add debugger-mcp -- npx debugger-mcp

MCP Tools

start_debug_session

Starts the HTTP log receiver and returns the endpoint URL + API spec.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | appid | string | yes | Unique session ID, e.g. "checkout-bug" | | port | number | no | HTTP server port (default: 7878) |

wait_for_logs

Blocks until logs arrive for the given appid, or until the timeout elapses. Returns immediately if logs were already collected.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | appid | string | yes | Session ID from start_debug_session | | timeout_ms | number | no | Max wait time in ms (default: 60000, max: 300000) |

get_logs

Returns all currently collected logs without blocking.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | appid | string | yes | Session ID |

clear_logs

Clears collected logs. Use between debug iterations to start fresh. Omit appid to clear all sessions.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | appid | string | no | Session to clear (omit to clear all) |

HTTP Log API

Once a session is started, your code sends logs via HTTP POST:

POST http://localhost:7878/log
Content-Type: application/json

{
  "appid":   "checkout-bug",
  "message": "user clicked checkout",
  "data":    { "cartId": 42, "userId": "u_99" },
  "level":   "info"
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | appid | string | yes | Must match the session ID | | message | string | yes | Label for this log point | | data | any JSON | no | Variables, state, response bodies, etc. | | level | "info" | "warn" | "error" | no | Default: "info" |

The server sets Access-Control-Allow-Origin: *, so browser fetch() calls work without CORS issues.

Language examples

JavaScript / TypeScript

fetch("http://localhost:7878/log", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ appid: "checkout-bug", message: "cart loaded", data: cart })
});

Python

import requests
requests.post("http://localhost:7878/log", json={"appid": "checkout-bug", "message": "cart loaded", "data": cart})

Go

import "net/http"; import "bytes"
http.Post("http://localhost:7878/log", "application/json",
  bytes.NewBufferString(`{"appid":"checkout-bug","message":"cart loaded","data":{}}`))

curl

curl -s -X POST http://localhost:7878/log \
  -H "Content-Type: application/json" \
  -d '{"appid":"checkout-bug","message":"cart loaded","data":{}}'

Example debugging session

User: The checkout total is wrong — it's not applying the discount code.

The agent will:

1. Form hypotheses about the root cause
2. Call start_debug_session({ appid: "discount-bug" })
3. Inject log calls at:
   • Entry of the discount function (with the code and cart as input)
   • The conditional that checks if the code is valid
   • The final computed total before it's returned
4. Tell you: "I've added temporary debug logs. Please enter discount code SAVE10 and proceed to checkout. Let me know when you've done that."
5. Call wait_for_logs({ appid: "discount-bug" }) — blocks until your action triggers the logs
6. Analyze the logs, find the bug, fix it, and remove all temporary logging lines

Development

npm run dev    # watch mode (tsc --watch)
npm run build  # compile to build/
npm start      # run the built server

License

MIT