node-runtime
Provides a debugger for a live Node.js process via the V8 Inspector protocol, letting the agent launch or attach to a Node script, set conditional breakpoints, step through execution, inspect stack frames and scopes, evaluate expressions in a paused frame, and read stdout/stderr and console output.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@node-runtime The /users/:id endpoint returns the wrong total for VIP carts. Find out why."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Start |
| Attach to a process already started with |
| Kill a launched process, or detach from an attached one. |
| What's attached, paused/running, current stack. |
|
|
| Manage breakpoints; hit counts included. Breakpoints survive relaunches. |
|
|
| Each returns the next pause location, or |
| Interrupt a running process. |
| Block until the next breakpoint/exception — e.g. after you fire an HTTP request at the app. |
| Full call stack with frame indices. |
| Every variable visible in a frame: local, closure, block, module, |
| Any JS expression, in a paused frame or (while running) in the global scope with |
| Expand an object by the |
| stdout, stderr, console.* and uncaught exceptions, with seq numbers and grep. |
| 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 projectOr 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 userUpdate 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.shDrop --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/:idendpoint returns the wrong total for VIP carts. Find out why."
Claude, with the tools:
launchsrc/server.jswithenv: {PORT: "3001"}.set_breakpointsrc/pricing.js:24with conditioncart.tier === "vip".Fires a request with its own HTTP tool, then
wait_for_pause.get_scopes→ seessub = 160, discount = 0.1, tax = undefined.step_overtwice,evaluatetax→11.52. The discount is applied before tax rather than after.continue,get_outputto 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 vianode_args(e.g.["--experimental-strip-types"]or["--import", "tsx"]); the script URL stays the.tspath and you set breakpoints there. Node's type stripping preserves line numbers exactly (tested intest/ts_smoke.mjs);tsx/esbuild mostly do, but it isn't guaranteed. Proper source-map translation is the obvious next feature.Idle processes.
pauseon 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 theNODE_RUNTIME_MCP_BLACKBOXenv 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=1to 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 SDKAvailable Tools
20 toolsattachAttach 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
Scored across 20 tools
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 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.
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.
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
Related MCP Connectors
Live browser debugging for AI assistants — DOM, console, network via MCP.
Build, debug and break hosted mock APIs from Claude: endpoints, stateful CRUD data, OpenAPI import, response variants and fault injection.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Launch, inspect, control, and share isolated cloud browsers for your agents.
Related MCP Servers
- AlicenseBqualityFmaintenanceAllows Claude to directly debug a NodeJS server by setting breakpoints, inspecting variables and stepping through code.13843 npm301MIT
- AlicenseBqualityDmaintenanceProvides Node.js debugging capabilities with process management for AI agents, allowing them to start/stop Node.js processes, set breakpoints, step through code, and evaluate expressions.816MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to debug Node.js applications using Chrome DevTools Protocol. Provides comprehensive debugging capabilities including breakpoints, stepping, variable inspection, expression evaluation, and console monitoring.4,585 npm351MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to debug JavaScript and TypeScript applications by connecting to Chrome DevTools Protocol-compatible debuggers, allowing them to set breakpoints, step through code, inspect variables, and evaluate expressions with full source map support.182Apache 2.0