inspector-mcp

A full Node.js debugger for AI agents, powered by Chrome DevTools Protocol.

Your AI can already read and write code. With inspector-mcp it can also run it, pause it, and look inside it.

Connect any MCP-compatible AI agent to a running Node.js process. Set breakpoints on your TypeScript source files, step through execution line by line, inspect every variable in scope, and read console output — all through natural language, without leaving your AI chat.

Table of Contents

• Features
• Requirements
• Installation
• Setup
• Make your AI smarter with the skill
• Available tools
• How it works
• Troubleshooting
• License

Features

• Source-map aware breakpoints — set breakpoints using your .ts file paths; the server resolves them to the compiled .js positions automatically
• Full step execution — step over, step into, step out, continue
• Variable inspection — local, closure, and global scope; drill into nested objects
• Expression evaluation — run any JS expression in the context of the paused frame
• Console buffer — last 1,000 log entries, filterable by level and text
• Auto-reconnect — survives process restarts and re-registers all breakpoints automatically
• Works with any MCP client — Claude Desktop, Cursor, VS Code, or any client supporting MCP stdio transport

Requirements

• Node.js ≥ 18
• Your app running with --inspect or --inspect-brk
• An MCP-compatible AI client

Installation

Try it without installing:

npx inspector-mcp

Install globally:

npm install -g inspector-mcp

Setup

1. Start your app in debug mode

# Node.js
node --inspect src/server.js

# Next.js
NODE_OPTIONS='--inspect' next dev

# nodemon
nodemon --inspect src/server.js

# Pause on first line (useful for startup bugs)
node --inspect-brk src/server.js

2. Register the MCP server with your AI client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "inspector": {
      "command": "npx",
      "args": ["inspector-mcp"]
    }
  }
}

Cursor / VS Code (.cursor/mcp.json or .vscode/mcp.json):

{
  "servers": {
    "inspector": {
      "command": "npx",
      "args": ["inspector-mcp"]
    }
  }
}

Claude Code (.mcp.json at your project root):

{
  "mcpServers": {
    "inspector": {
      "type": "stdio",
      "command": "npx",
      "args": ["inspector-mcp"]
    }
  }
}

3. Ask your AI to debug

Once the MCP server is connected, describe the problem in plain language:

My /api/users endpoint is returning 500. Connect to the process on port 9229,
set a breakpoint at line 34 of src/routes/users.ts, and tell me what the
database query result looks like when the error happens.

The agent will connect, set the breakpoint, wait for the pause, and report back with the actual values — no extra tooling needed.

Make your AI smarter with the skill

The skills/inspector-mcp/SKILL.md file in this repo is a ready-to-use skill that teaches your AI exactly how to use this tool — the correct workflow order, pitfalls to avoid, and advanced tips.

Add it to your project so your AI agent picks it up automatically:

mkdir -p .claude/skills/inspector-mcp
curl -o .claude/skills/inspector-mcp/SKILL.md \
  https://raw.githubusercontent.com/AbianS/inspector-mcp/main/skills/inspector-mcp/SKILL.md

Once in place, your AI will know how to connect, set breakpoints, and inspect variables correctly — without you having to explain it every time.

Available tools

🔌 Connection

| Tool | Description | |---|---| | debug_connect | Connect to a Node.js process. Accepts host, port, and auto_reconnect. | | debug_disconnect | Close a session. | | debug_list_sessions | List active sessions and their status (connecting / connected / paused / reconnecting). |

🔴 Breakpoints

| Tool | Description | |---|---| | debug_set_breakpoint | Set a breakpoint on a .ts or .js file. Supports condition for conditional breaks. | | debug_remove_breakpoint | Remove a breakpoint by its ID. | | debug_list_breakpoints | List all breakpoints and whether they are verified (will trigger) or not. |

▶️ Execution

| Tool | Description | |---|---| | debug_continue | Resume until the next breakpoint. | | debug_pause | Pause at the next statement. | | debug_step_over | Next line — skip into function bodies. | | debug_step_into | Enter the next function call. | | debug_step_out | Run until the current function returns. |

🔍 Inspection (requires paused session)

| Tool | Description | |---|---| | debug_stack_trace | Current call stack with TypeScript file paths and line numbers. | | debug_get_variables | Variables in scope. Use scope_filter: local, closure, global, or all. | | debug_evaluate | Evaluate a JS expression in the paused frame. | | debug_get_properties | Expand a nested object using its objectId from get_variables. |

📋 Console

| Tool | Description | |---|---| | debug_read_console | Read buffered logs. Filter by level and filter text; paginate with limit / offset. | | debug_clear_console | Clear the buffer. |

How it works

Your AI ──(MCP / stdio)──► inspector-mcp ──(CDP / WebSocket)──► node --inspect
                                  │
                            source maps
                           (.ts ↔ .js)

inspector-mcp is a stdio MCP server. On debug_connect it opens a WebSocket to the Chrome DevTools Protocol endpoint that Node.js exposes on the --inspect port. Source maps are read from the compiled output to translate between TypeScript source positions and the generated JavaScript that's actually running. Console output is captured into a ring buffer as events arrive.

Troubleshooting

ECONNREFUSED on connect

The process is not running with --inspect, or is on a different port. Restart with:

node --inspect src/server.js   # port 9229
NODE_OPTIONS='--inspect' next dev  # port 9230

Breakpoint is verified: false and never triggers

Source maps are missing or the compiled file doesn't exist. Run a build first, then check:

ls build/server.js.map                # external source map
grep sourceMappingURL build/server.js # inline source map

As a fallback, set the breakpoint on the .js file in build/ directly and adjust the line number — TypeScript strips type annotations so lines shift by 1–3.

get_variables / evaluate return error -32600

The session is not paused. These tools only work when the process is stopped at a breakpoint. Verify with debug_list_sessions that status === "paused".

Variables show as [Object]

debug_get_variables returns shallow previews. Use debug_get_properties with the objectId to expand nested values.

License

MIT © Abian Suarez