Skip to main content
Glama

node-runtime-mcp

An MCP server that gives Claude Code a debugger for a live Node.js process. Instead of reasoning from static source back to what probably happened, Claude can set a breakpoint, run to it, read the locals, evaluate an expression in that frame, step, and read what the process printed — the same loop a developer runs in DevTools, exposed as tools.

It speaks the V8 Inspector protocol directly (the same one Chrome DevTools and VS Code use), so it works with any Node ≥ 18 script, CommonJS or ESM, with no instrumentation added to your code.

Tools

Tool

What it does

launch

Start node <script> [args] under the debugger. Paused at line 1 while breakpoints are applied, then runs (or stays paused with stop_on_entry).

attach

Attach to a process already started with node --inspect / --inspect-brk (default 127.0.0.1:9229).

disconnect

Kill a launched process, or detach from an attached one.

status

What's attached, paused/running, current stack.

set_breakpoint

file:line, optional JS condition. Resolves lazily if the file hasn't loaded yet.

remove_breakpoint, list_breakpoints

Manage breakpoints; hit counts included. Breakpoints survive relaunches.

set_exception_breakpoints

none / uncaught (default) / all.

continue, step_over, step_into, step_out

Each returns the next pause location, or running after wait_ms.

pause

Interrupt a running process.

wait_for_pause

Block until the next breakpoint/exception — e.g. after you fire an HTTP request at the app.

get_stack

Full call stack with frame indices.

get_scopes

Every variable visible in a frame: local, closure, block, module, this.

evaluate

Any JS expression, in a paused frame or (while running) in the global scope with require available. Side effects allowed.

get_properties

Expand an object by the ⟨ref …⟩ shown in get_scopes / evaluate output.

get_output

stdout, stderr, console.* and uncaught exceptions, with seq numbers and grep.

list_scripts

Source files the process has loaded (handy for finding the right breakpoint path).

Line numbers are 1-based everywhere. Paths resolve against the launch cwd.

Related MCP server: Node.js Debugger MCP Server

Install

Requires Node 18+ and git. The plugin installs its own npm dependencies and builds itself the first time it starts (one-time, ~20 s), so there is no manual build step.

As a Claude Code plugin

Through the keith-tools marketplace, which also carries jec-index and deliberate:

claude plugin marketplace add keiththornton/claude-plugins
claude plugin install node-runtime@keith-tools --scope user     # or --scope project

Or straight from this repository, which is its own single-plugin marketplace:

claude plugin marketplace add keiththornton/node-runtime-mcp
claude plugin install node-runtime@node-runtime --scope user

Update later with claude plugin update node-runtime@keith-tools.

Manual setup (plain MCP server)

git clone https://github.com/keiththornton/node-runtime-mcp.git ~/Code/node-runtime-mcp
claude mcp add --scope user node-runtime -- bash ~/Code/node-runtime-mcp/bin/launch.sh

Drop --scope user to register it for the current project only, or commit a .mcp.json in the project:

{
  "mcpServers": {
    "node-runtime": {
      "command": "bash",
      "args": ["/absolute/path/to/node-runtime-mcp/bin/launch.sh"]
    }
  }
}

bin/launch.sh runs npm ci (which builds dist/) if either is missing, then starts node dist/index.js. For development: npm install && npm run build && npm test (the tests debug the programs in examples/).

The server's working directory is where Claude Code is running, so relative script and breakpoint paths resolve against your project.

What a session looks like

"The /users/:id endpoint returns the wrong total for VIP carts. Find out why."

Claude, with the tools:

  1. launch src/server.js with env: {PORT: "3001"}.

  2. set_breakpoint src/pricing.js:24 with condition cart.tier === "vip".

  3. Fires a request with its own HTTP tool, then wait_for_pause.

  4. get_scopes → sees sub = 160, discount = 0.1, tax = undefined.

  5. step_over twice, evaluate tax → 11.52. The discount is applied before tax rather than after.

  6. continue, get_output to confirm the printed total, disconnect, then edits the code.

Notes and limitations

  • TypeScript / source maps. v1 does not translate source maps: breakpoints and stack frames use the file and line numbers V8 actually executes. For pre-compiled output, set breakpoints in the emitted .js. For in-process runners (Node's own --experimental-strip-types, tsx, ts-node), pass the flags via node_args (e.g. ["--experimental-strip-types"] or ["--import", "tsx"]); the script URL stays the .ts path and you set breakpoints there. Node's type stripping preserves line numbers exactly (tested in test/ts_smoke.mjs); tsx/esbuild mostly do, but it isn't guaranteed. Proper source-map translation is the obvious next feature.

  • Idle processes. pause on a process that is waiting on I/O has nothing to pause; it lands at the next JS execution, which may be a Node-internal timer. The tool says so when every frame is internal.

  • One session at a time. Launching or attaching tears down the previous session. Breakpoints are remembered across sessions so relaunch → hit the same breakpoint works.

  • Node internals are ignore-listed (node:*) so steps and pauses land in your code. Add your own patterns with the NODE_RUNTIME_MCP_BLACKBOX env var (a regex), e.g. node_modules.

  • Worker threads have their own inspector targets and aren't covered.

  • Debugging the protocol. Set NODE_RUNTIME_MCP_DEBUG=1 to trace every inspector message on stderr.

Roadmap

  • Source-map aware breakpoints and stack frames.

  • Logpoints (print an expression at a line without pausing).

  • HTTP request/response tap and structured log tail.

  • Python adapter via debugpy behind the same tool surface.

Layout

src/inspector.ts   WebSocket client for the Inspector protocol
src/session.ts     launch/attach, breakpoints, execution control, inspection
src/format.ts      renders RemoteObjects into short readable strings
src/index.ts       MCP server: tool definitions
examples/          small programs the tests debug
test/              end-to-end tests driven through the MCP client SDK

Available Tools

20 tools
attachAttach to a running Node processA

Attach to a process already started with node --inspect or --inspect-brk (default 127.0.0.1:9229). Does not take ownership of the process; disconnect detaches and lets it keep running. Breakpoint paths are resolved against the server's cwd unless they're absolute.

Inputs: host, port, ws_url.

continueResume executionA

Resume the paused process. Returns the next pause (breakpoint, exception, debugger statement) if one happens within wait_ms, otherwise 'running'.

Inputs: wait_ms.

disconnectEnd the debug sessionA

Kill a launched process, or detach from an attached one (resuming it if paused). Breakpoints are remembered for the next launch/attach.

Inputs: no named parameters.

evaluateEvaluate an expressionA

Evaluate a JavaScript expression. While paused it runs in the chosen frame (default innermost) and can see locals; while running it runs in the global scope with require available (paths relative to the process cwd) and awaits promises. Side effects are allowed, so this can also mutate state or call functions. If the expression calls into code that hits a breakpoint, the pause is reported and the process stays paused there.

Inputs: expression (required), frame.

get_outputProcess outputA

stdout, stderr, console.* calls and uncaught exceptions captured from the process, newest last. Each line has a seq number; pass since_seq to get only new lines.

Inputs: grep, limit, source, since_seq.

get_propertiesExpand an objectA

List the properties of an object by the ⟨ref …⟩ id shown by get_scopes or evaluate. Nested objects get their own refs.

Inputs: ref (required), own_only.

get_scopesVariables in a frameA

All variables visible in a frame (local, closure, block, module scopes, plus this), with values. Object values come with a ⟨ref⟩ you can expand with get_properties.

Inputs: frame, include_global.

get_stackCall stackA

The full call stack at the current pause: frame index, function name, file:line:col. Frame indices are used by get_scopes and evaluate.

Inputs: no named parameters.

launchLaunch a Node script under the debuggerA

Start node <script> [args] with the inspector attached. The process is paused at its first line until breakpoints are applied, then resumed unless stop_on_entry is true. Any previous session is torn down first.

Inputs: script (required), cwd, env, args, +2 more.

list_breakpointsList breakpointsB

All breakpoints with their ids, locations, conditions, resolution state and hit counts.

Inputs: no named parameters.

list_scriptsLoaded scriptsA

Source files the process has loaded so far (excluding node: internals). Useful to find the right path for a breakpoint.

Inputs: filter.

pausePause the running processA

Interrupt a running process at the next JS execution and report where it stopped.

Inputs: wait_ms.

remove_breakpointRemove a breakpointB

Remove a breakpoint by the id returned from set_breakpoint.

Inputs: id (required).

set_breakpointSet a breakpointA

Set a (optionally conditional) breakpoint at file:line. Line is 1-based. The file may not be loaded yet; the breakpoint resolves when it is. Returns the breakpoint id to use with remove_breakpoint.

Inputs: file (required), line (required), condition.

set_exception_breakpointsPause on exceptionsA

Control whether the debugger pauses when an exception is thrown. Default is 'uncaught'.

Inputs: mode (required).

statusSession statusB

Whether a session is active, what it's attached to, paused/running, breakpoint count, and the current stack if paused.

Inputs: no named parameters.

step_intoStep intoA

Step into the function called on the current line (follows async calls).

Inputs: wait_ms.

step_outStep outB

Run until the current function returns and pause in the caller.

Inputs: wait_ms.

step_overStep overA

Execute the current line and pause on the next one in the same frame.

Inputs: wait_ms.

wait_for_pauseWait for the next pauseA

Block up to wait_ms for the running process to hit a breakpoint or exception, e.g. after you trigger an HTTP request against it from elsewhere.

Inputs: wait_ms.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool targets a distinct debugger action: session lifecycle (launch/attach/disconnect/status), inspection (get_stack/get_scopes/get_properties/get_output/evaluate), breakpoints (set/remove/list/set_exception_breakpoints), and execution control (continue/pause/step_over/step_into/step_out/wait_for_pause). Overlaps are minimal and handled by clear scoping (e.g. evaluate vs get_properties, continue vs wait_for_pause). An agent can reliably pick the right tool.

    Naming Consistency4/5

    Naming is largely readable and predictable, with verb_noun forms for most tools (get_stack, set_breakpoint, remove_breakpoint, list_breakpoints, step_over, wait_for_pause). Deviations are single-action verbs (launch, attach, disconnect, continue, pause, evaluate, status), which are conventional in debugger APIs but technically mixed with the verb_noun pattern.

    Tool Count4/5

    At 20 tools this is on the heavier side for a typical MCP server, but the Node.js debugging domain genuinely requires lifecycle, inspection, breakpoint, and stepping primitives. Each tool appears to earn its place, with no obvious redundant entries, so the count is reasonable though slightly over the ideal 3-15 range.

    Completeness4/5

    Core debugger workflows are well covered: launch/attach, session teardown, breakpoint management including conditional and exception breakpoints, stack/scope/property inspection, evaluation, output capture, and full stepping controls. Minor gaps exist, such as no explicit tool to read a loaded script's source (list_scripts only enumerates paths) and no bulk breakpoint removal, but these are workable.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers