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

bash

npm install devtools-debugger-mcp

Or globally:

bash

npm install -g devtools-debugger-mcp

Configuration

MCP Settings

Add to your MCP client configuration (e.g., Claude Desktop's

claude_desktop_config.json

json

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

Or if installed globally:

json

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

Output Format

Set default response format (

text

json

, or

both

javascript

// 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

javascript

// 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:

javascript

{
  "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):

javascript

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

Conditional breakpoint:

javascript

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

URL regex breakpoint (for modules/packages):

javascript

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

Logpoint (logs message without pausing):

javascript

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

3. Exception Breakpoints

javascript

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

4. Resume and Step

Resume to next breakpoint:

javascript

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

Step over current line:

javascript

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

Step into function:

javascript

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

Step out of current function:

javascript

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

Continue to specific location:

javascript

{
  "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):

javascript

{
  "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:

javascript

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

6. Evaluate Expressions

javascript

{
  "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:

javascript

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

7. Call Stack Inspection

javascript

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

8. Pause Information

javascript

{
  "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

javascript

{
  "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

javascript

{
  "tool": "stop_debug_session"
}

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

Script Management

List Loaded Scripts

javascript

{
  "tool": "list_scripts"
}

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

Get Script Source

javascript

// 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)

javascript

{
  "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:

javascript

{
  "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:

javascript

{
  "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

javascript

// 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

javascript

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

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

Multi-Frame Inspection

javascript

// 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

javascript

// 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

javascript

// 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

javascript

// 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

javascript

// ✅ 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')
```
)

javascript

// 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

javascript

// 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

javascript

// 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
```

javascript

// 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

javascript

// 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
```

bash

# 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

javascript

// 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:

javascript

{
  "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

NPX Install

Tags

SKILL.md Content

devtools-debugger-mcp-nodejs

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