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

Use absolute paths: Always provide absolute file paths for breakpoints
Include context: Add includeScopes, includeStack, includeConsole on steps for richer debugging
Blackbox dependencies: Skip node_modules during step-into with blackbox_scripts
Conditional breakpoints: Use conditions to pause only when specific criteria met
Logpoints over breakpoints: Use logpoints for non-intrusive logging without pausing
Pause on uncaught only: Set state: 'uncaught' to avoid pausing on handled exceptions
Clean up sessions: Always call stop_debug_session when done
Test with simple scripts: Verify setup with minimal examples before complex debugging
Check pauseId: After each pause, note the pauseId for context-specific operations
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

devtools-debugger-mcp-nodejs

About this skill

What It Does

Installation

Configuration

MCP Settings

Output Format

Core Debugging Workflow

1. Start Debug Session

2. Set Breakpoints

3. Exception Breakpoints

4. Resume and Step

5. Inspect Variables and Scopes

6. Evaluate Expressions

7. Call Stack Inspection

8. Pause Information

9. Console Output

10. Stop Session

Script Management

List Loaded Scripts

Get Script Source

Blackbox Scripts (Skip During Debugging)

Restart Frame

Advanced Patterns

Debug TypeScript with Source Maps

Conditional Debugging Loop

Capture All Console Output

Multi-Frame Inspection

Exception Debugging

Real-World Example: Debug Express API

Real-World Example: Debug Async/Await

File Path Handling

Troubleshooting

Session Won't Start

Breakpoint Not Hit

Source Maps Not Working

Can't Inspect Large Objects

Console Output Missing

Session Cleanup

Multiple Pauses

Tips and Best Practices

Environment Variables

License