Devtools Debugger MCP Nodejs

devtools-debugger-mcp-nodejs

Skill by ara.so — Devtools Skills collection.

An MCP (Model Context Protocol) server that exposes comprehensive Node.js debugging capabilities through the Chrome DevTools Protocol. Enables AI assistants to set breakpoints, step through code, inspect variables, evaluate expressions, analyze call stacks, and work with source maps — all programmatically.

What It Does

This MCP server launches Node.js applications with the built-in inspector (--inspect-brk=0), connects via WebSocket to the Chrome DevTools Protocol, and exposes debugging operations as MCP tools. It handles:

• Session management: Launch/stop Node.js processes with debugging enabled
• Breakpoints: Set line breakpoints, conditional breakpoints, logpoints, and pause-on-exceptions
• Execution control: Resume, step over/into/out, continue to location, restart frames
• Inspection: Explore scopes (locals, closures, this), drill into object properties
• Evaluation: Execute JavaScript expressions in paused call frames
• Console capture: Buffer and retrieve console output between pauses
• Source maps: Full TypeScript and transpiled code debugging support
• Script management: List loaded scripts, fetch sources, blackbox patterns

Installation

npm install devtools-debugger-mcp

Or globally:

npm install -g devtools-debugger-mcp

Configuration

MCP Settings

Add to your MCP client configuration (e.g., Claude Desktop's claude_desktop_config.json):

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

Or if installed globally:

{
  "mcpServers": {
    "devtools-debugger": {
      "command": "devtools-debugger-mcp"
    }
  }
}

Output Format

Set default response format (text, json, or both):

// Via set_output_format tool (defaults to 'text')
{
  "tool": "set_output_format",
  "params": { "format": "json" }
}

Individual tools can override with their own format parameter.

Core Debugging Workflow

1. Start Debug Session

// Launch Node.js script with inspector
{
  "tool": "start_node_debug",
  "params": {
    "scriptPath": "/absolute/path/to/app.js",
    "format": "text"  // optional: 'text' | 'json' | 'both'
  }
}

Returns initial pause at first line with pauseId and top frame info.

With arguments and environment:

{
  "tool": "start_node_debug",
  "params": {
    "scriptPath": "/path/to/server.js",
    "args": ["--port", "3000"],
    "env": {
      "NODE_ENV": "development",
      "DEBUG": "*"
    }
  }
}

2. Set Breakpoints

File path + line (1-based):

{
  "tool": "set_breakpoint",
  "params": {
    "filePath": "/path/to/app.js",
    "line": 42
  }
}

Conditional breakpoint:

{
  "tool": "set_breakpoint_condition",
  "params": {
    "filePath": "/path/to/users.js",
    "line": 15,
    "condition": "user.age > 18"
  }
}

URL regex breakpoint (for modules/packages):

{
  "tool": "set_breakpoint_condition",
  "params": {
    "urlRegex": ".*express.*",
    "line": 100,
    "condition": "req.method === 'POST'"
  }
}

Logpoint (logs message without pausing):

{
  "tool": "add_logpoint",
  "params": {
    "filePath": "/path/to/api.js",
    "line": 28,
    "message": "Request received: {req.url}"
  }
}

3. Exception Breakpoints

{
  "tool": "set_exception_breakpoints",
  "params": {
    "state": "uncaught"  // 'none' | 'uncaught' | 'all'
  }
}

4. Resume and Step

Resume to next breakpoint:

{
  "tool": "resume_execution",
  "params": {
    "includeScopes": true,
    "includeStack": true,
    "includeConsole": true,
    "format": "text"
  }
}

Step over current line:

{
  "tool": "step_over",
  "params": {
    "includeScopes": true,
    "includeConsole": true
  }
}

Step into function:

{
  "tool": "step_into",
  "params": {
    "includeStack": true
  }
}

Step out of current function:

{
  "tool": "step_out",
  "params": {
    "includeScopes": true
  }
}

Continue to specific location:

{
  "tool": "continue_to_location",
  "params": {
    "filePath": "/path/to/app.js",
    "line": 55,
    "column": 10  // optional
  }
}

5. Inspect Variables and Scopes

Current scope (locals, closures, this):

{
  "tool": "inspect_scopes",
  "params": {
    "maxProps": 20,          // max properties per object
    "pauseId": "pause123",   // optional, defaults to current
    "frameIndex": 0,         // optional, defaults to 0 (top frame)
    "includeThisPreview": true,
    "format": "text"
  }
}

Drill into object properties:

// First get objectId from inspect_scopes or evaluate_expression
{
  "tool": "get_object_properties",
  "params": {
    "objectId": "object:123",
    "maxProps": 50
  }
}

6. Evaluate Expressions

{
  "tool": "evaluate_expression",
  "params": {
    "expr": "user.profile.email",
    "pauseId": "pause123",     // optional
    "frameIndex": 0,           // optional, which frame to eval in
    "returnByValue": true,     // optional, serialize result
    "format": "json"
  }
}

Evaluate with side effects:

{
  "tool": "evaluate_expression",
  "params": {
    "expr": "items.push({ id: 5, name: 'test' }); items.length"
  }
}

7. Call Stack Inspection

{
  "tool": "list_call_stack",
  "params": {
    "depth": 10,              // optional, max frames
    "pauseId": "pause123",    // optional
    "includeThis": true,      // optional, include 'this' preview
    "format": "text"
  }
}

8. Pause Information

{
  "tool": "get_pause_info",
  "params": {
    "pauseId": "pause123",    // optional, defaults to current
    "format": "text"
  }
}

Returns pause reason (breakpoint, exception, step, etc.) and location.

9. Console Output

{
  "tool": "read_console",
  "params": {
    "format": "text"
  }
}

Retrieves console messages buffered since last step/resume. Console is also auto-included when includeConsole: true on step/resume tools.

10. Stop Session

{
  "tool": "stop_debug_session"
}

Kills the Node.js process and cleans up CDP connection.

Script Management

List Loaded Scripts

{
  "tool": "list_scripts"
}

Returns all scripts loaded by Node.js (app files, node_modules, builtins).

Get Script Source

// By scriptId
{
  "tool": "get_script_source",
  "params": {
    "scriptId": "42"
  }
}

// By URL
{
  "tool": "get_script_source",
  "params": {
    "url": "file:///path/to/app.js"
  }
}

Blackbox Scripts (Skip During Debugging)

{
  "tool": "blackbox_scripts",
  "params": {
    "patterns": [
      "node_modules/express/*",
      "internal/*"
    ]
  }
}

Frames matching these patterns won't pause during step-into.

Restart Frame

Re-execute a specific call frame:

{
  "tool": "restart_frame",
  "params": {
    "frameIndex": 2,          // which frame to restart (0 = top)
    "pauseId": "pause123",    // optional
    "format": "text"
  }
}

Advanced Patterns

Debug TypeScript with Source Maps

Source maps are automatically detected and used. Just launch your compiled JS:

{
  "tool": "start_node_debug",
  "params": {
    "scriptPath": "/path/to/dist/app.js"
  }
}

// Set breakpoints using original .ts file paths
{
  "tool": "set_breakpoint",
  "params": {
    "filePath": "/path/to/src/app.ts",
    "line": 42
  }
}

Conditional Debugging Loop

// 1. Start session
start_node_debug({ scriptPath: "/path/to/app.js" })

// 2. Set conditional breakpoint
set_breakpoint_condition({
  filePath: "/path/to/app.js",
  line: 25,
  condition: "count > 100"
})

// 3. Resume until condition met
resume_execution({ includeScopes: true, includeConsole: true })

// 4. Inspect when paused
inspect_scopes({ maxProps: 15 })
evaluate_expression({ expr: "count" })

// 5. Continue
resume_execution()

Capture All Console Output

// Resume with console capture
const result = await resume_execution({ includeConsole: true });

// Or read explicitly
const consoleOutput = await read_console({ format: "text" });

Multi-Frame Inspection

// Get full call stack
list_call_stack({ depth: 20, includeThis: true })

// Inspect different frames
inspect_scopes({ frameIndex: 0 })  // Current frame
inspect_scopes({ frameIndex: 1 })  // Caller frame
inspect_scopes({ frameIndex: 2 })  // Caller's caller

// Evaluate in different frame context
evaluate_expression({ expr: "localVar", frameIndex: 1 })

Exception Debugging

// Pause on all exceptions
set_exception_breakpoints({ state: "all" })

// Resume and wait for exception
const result = await resume_execution({ includeStack: true })

// When paused on exception:
get_pause_info()  // Shows exception details
list_call_stack({ depth: 10 })
inspect_scopes({ maxProps: 20 })

Real-World Example: Debug Express API

// 1. Start debugging an Express server
{
  "tool": "start_node_debug",
  "params": {
    "scriptPath": "/path/to/server.js",
    "env": {
      "PORT": "3000",
      "NODE_ENV": "development"
    }
  }
}

// 2. Set breakpoint in route handler
{
  "tool": "set_breakpoint",
  "params": {
    "filePath": "/path/to/routes/users.js",
    "line": 15
  }
}

// 3. Set logpoint to track requests
{
  "tool": "add_logpoint",
  "params": {
    "filePath": "/path/to/middleware/auth.js",
    "line": 8,
    "message": "Auth check for user: {req.user.id}"
  }
}

// 4. Pause only on errors
{
  "tool": "set_exception_breakpoints",
  "params": { "state": "uncaught" }
}

// 5. Resume and make HTTP request (externally)
{
  "tool": "resume_execution",
  "params": {
    "includeScopes": true,
    "includeConsole": true
  }
}

// 6. When paused at breakpoint, inspect request
{
  "tool": "evaluate_expression",
  "params": {
    "expr": "req.body",
    "returnByValue": true
  }
}

{
  "tool": "evaluate_expression",
  "params": {
    "expr": "req.headers['authorization']"
  }
}

// 7. Check database query in scope
{
  "tool": "inspect_scopes",
  "params": { "maxProps": 30 }
}

// 8. Step into database function
{
  "tool": "step_into",
  "params": { "includeStack": true }
}

// 9. Continue execution
{
  "tool": "resume_execution"
}

// 10. Stop when done
{
  "tool": "stop_debug_session"
}

Real-World Example: Debug Async/Await

// app.js
async function fetchUserData(userId) {
  const user = await db.findUser(userId);
  const posts = await db.findPosts(user.id);
  return { user, posts };
}

// Debugging session:

// 1. Start
start_node_debug({ scriptPath: "/path/to/app.js" })

// 2. Break at async function
set_breakpoint({ filePath: "/path/to/app.js", line: 2 })

// 3. Resume to breakpoint
resume_execution({ includeScopes: true })

// 4. Check userId parameter
evaluate_expression({ expr: "userId" })

// 5. Step over await (resumes until promise resolves)
step_over({ includeScopes: true, includeConsole: true })

// 6. Inspect resolved user object
evaluate_expression({ expr: "user" })
get_object_properties({ objectId: "object:user123", maxProps: 20 })

// 7. Continue
resume_execution()

File Path Handling

• Always use absolute paths for filePath parameters
• Relative paths are NOT resolved automatically
• Internal conversion: file paths → file:// URLs for CDP
• Line numbers are 1-based (CDP internally uses 0-based)
• Column numbers are 1-based when specified

// ✅ Correct
set_breakpoint({ filePath: "/home/user/project/src/app.js", line: 42 })

// ❌ Wrong (relative path)
set_breakpoint({ filePath: "./src/app.js", line: 42 })

Troubleshooting

Session Won't Start

Problem: start_node_debug fails or hangs

Solutions:

• Ensure scriptPath is an absolute path
• Check that the script file exists and is readable
• Verify Node.js is in PATH
• Try with a simple script first (e.g., console.log('test'))

// Test with minimal script
start_node_debug({ scriptPath: "/tmp/test.js" })
// test.js content: console.log('Hello');

Breakpoint Not Hit

Problem: Breakpoint set but execution doesn't pause

Solutions:

• Verify file path matches exactly (use list_scripts to confirm)
• Check line number is valid (1-based, not 0-based)
• Ensure breakpoint isn't in unreachable code
• Try URL regex if file path doesn't match

// List all scripts to find exact URL
list_scripts()

// Use URL regex instead of file path
set_breakpoint_condition({
  urlRegex: ".*app\\.js$",
  line: 42
})

Source Maps Not Working

Problem: Breakpoints in TypeScript sources don't work

Solutions:

• Ensure source maps are generated ("sourceMap": true in tsconfig.json)
• Check .map files exist alongside compiled JS
• Verify source map paths are correct (relative or absolute)
• Use compiled JS path if source map lookup fails

// If TypeScript breakpoints fail, use compiled JS path
set_breakpoint({ filePath: "/path/to/dist/app.js", line: 58 })

Can't Inspect Large Objects

Problem: Objects truncated or not showing all properties

Solutions:

• Increase maxProps parameter
• Use get_object_properties to drill down
• Evaluate specific property paths with evaluate_expression

// Get more properties
inspect_scopes({ maxProps: 100 })

// Or drill into specific object
evaluate_expression({ expr: "largeObject.specificProperty" })

Console Output Missing

Problem: Console logs not captured

Solutions:

• Use includeConsole: true on step/resume operations
• Or call read_console explicitly after stepping
• Console buffer is cleared after each read

// Include console in step
step_over({ includeConsole: true })

// Or read explicitly
read_console({ format: "text" })

Session Cleanup

Problem: Zombie Node.js processes after debugging

Solutions:

• Always call stop_debug_session when done
• MCP server cleans up on disconnect, but explicit stop is better
• Check for orphaned Node.js processes: ps aux | grep node

# Kill orphaned debugger processes
pkill -f "node --inspect-brk"

Multiple Pauses

Problem: Execution pauses unexpectedly

Solutions:

• Check for multiple breakpoints at same location
• Review exception breakpoint settings (set_exception_breakpoints)
• Use get_pause_info to understand why paused
• Remove breakpoints: restart session or use CDP commands directly

// Check why paused
get_pause_info({ format: "text" })

// Disable exception breaks if too noisy
set_exception_breakpoints({ state: "none" })

Tips and Best Practices

1. Use absolute paths: Always provide absolute file paths for breakpoints
2. Include context: Add includeScopes, includeStack, includeConsole on steps for richer debugging
3. Blackbox dependencies: Skip node_modules during step-into with blackbox_scripts
4. Conditional breakpoints: Use conditions to pause only when specific criteria met
5. Logpoints over breakpoints: Use logpoints for non-intrusive logging without pausing
6. Pause on uncaught only: Set state: 'uncaught' to avoid pausing on handled exceptions
7. Clean up sessions: Always call stop_debug_session when done
8. Test with simple scripts: Verify setup with minimal examples before complex debugging
9. Check pauseId: After each pause, note the pauseId for context-specific operations
10. Frame-aware evaluation: Use frameIndex to evaluate expressions in specific call frames

Environment Variables

The MCP server itself doesn't require environment variables, but your Node.js scripts may:

{
  "tool": "start_node_debug",
  "params": {
    "scriptPath": "/path/to/app.js",
    "env": {
      "DATABASE_URL": process.env.DATABASE_URL,
      "API_KEY": process.env.API_KEY,
      "NODE_ENV": "development"
    }
  }
}

Never hardcode secrets in debugging params — reference environment variables or use a .env file in your project.

License

MIT