{"id":47733108,"url":"https://github.com/abians/inspector-mcp","last_synced_at":"2026-04-02T22:00:32.361Z","repository":{"id":348584569,"uuid":"1198813697","full_name":"AbianS/inspector-mcp","owner":"AbianS","description":"MCP server for debugging live Node.js processes via Chrome DevTools Protocol","archived":false,"fork":false,"pushed_at":"2026-04-01T19:43:48.000Z","size":83,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T07:21:30.671Z","etag":null,"topics":["breakpoints","cdp","chrome-devtools-protocol","debugger","inspector","mcp","model-context-protocol","source-maps"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/inspector-mcp","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AbianS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T19:33:07.000Z","updated_at":"2026-04-01T19:46:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AbianS/inspector-mcp","commit_stats":null,"previous_names":["abians/inspector-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/AbianS/inspector-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbianS%2Finspector-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbianS%2Finspector-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbianS%2Finspector-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbianS%2Finspector-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AbianS","download_url":"https://codeload.github.com/AbianS/inspector-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbianS%2Finspector-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31317830,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T21:35:00.834Z","status":"ssl_error","status_checked_at":"2026-04-02T21:34:59.806Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["breakpoints","cdp","chrome-devtools-protocol","debugger","inspector","mcp","model-context-protocol","source-maps"],"created_at":"2026-04-02T22:00:22.618Z","updated_at":"2026-04-02T22:00:32.294Z","avatar_url":"https://github.com/AbianS.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# inspector-mcp\n\n\u003e A full Node.js debugger for AI agents, powered by Chrome DevTools Protocol.\n\n[![npm version](https://img.shields.io/npm/v/inspector-mcp?style=flat-square)](https://www.npmjs.com/package/inspector-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/inspector-mcp?style=flat-square)](https://www.npmjs.com/package/inspector-mcp)\n[![CI](https://img.shields.io/github/actions/workflow/status/AbianS/inspector-mcp/ci.yml?branch=main\u0026style=flat-square\u0026label=CI)](https://github.com/AbianS/inspector-mcp/actions)\n[![Node \u003e=18](https://img.shields.io/node/v/inspector-mcp?style=flat-square)](https://nodejs.org)\n[![License: MIT](https://img.shields.io/npm/l/inspector-mcp?style=flat-square)](LICENSE)\n\n---\n\nYour AI can already read and write code. With `inspector-mcp` it can also **run it, pause it, and look inside it**.\n\nConnect 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.\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Setup](#setup)\n- [Make your AI smarter with the skill](#make-your-ai-smarter-with-the-skill)\n- [Available tools](#available-tools)\n- [How it works](#how-it-works)\n- [Troubleshooting](#troubleshooting)\n- [License](#license)\n\n---\n\n## Features\n\n- **Source-map aware breakpoints** — set breakpoints using your `.ts` file paths; the server resolves them to the compiled `.js` positions automatically\n- **Full step execution** — step over, step into, step out, continue\n- **Variable inspection** — local, closure, and global scope; drill into nested objects\n- **Expression evaluation** — run any JS expression in the context of the paused frame\n- **Console buffer** — last 1,000 log entries, filterable by level and text\n- **Auto-reconnect** — survives process restarts and re-registers all breakpoints automatically\n- **Works with any MCP client** — Claude Desktop, Cursor, VS Code, or any client supporting MCP stdio transport\n\n---\n\n## Requirements\n\n- **Node.js ≥ 18**\n- Your app running with `--inspect` or `--inspect-brk`\n- An [MCP-compatible AI client](https://modelcontextprotocol.io/clients)\n\n---\n\n## Installation\n\n**Try it without installing:**\n\n```sh\nnpx inspector-mcp\n```\n\n**Install globally:**\n\n```sh\nnpm install -g inspector-mcp\n```\n\n---\n\n## Setup\n\n### 1. Start your app in debug mode\n\n```sh\n# Node.js\nnode --inspect src/server.js\n\n# Next.js\nNODE_OPTIONS='--inspect' next dev\n\n# nodemon\nnodemon --inspect src/server.js\n\n# Pause on first line (useful for startup bugs)\nnode --inspect-brk src/server.js\n```\n\n### 2. Register the MCP server with your AI client\n\n**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"inspector\": {\n      \"command\": \"npx\",\n      \"args\": [\"inspector-mcp\"]\n    }\n  }\n}\n```\n\n**Cursor / VS Code** (`.cursor/mcp.json` or `.vscode/mcp.json`):\n\n```json\n{\n  \"servers\": {\n    \"inspector\": {\n      \"command\": \"npx\",\n      \"args\": [\"inspector-mcp\"]\n    }\n  }\n}\n```\n\n**Claude Code** (`.mcp.json` at your project root):\n\n```json\n{\n  \"mcpServers\": {\n    \"inspector\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"inspector-mcp\"]\n    }\n  }\n}\n```\n\n### 3. Ask your AI to debug\n\nOnce the MCP server is connected, describe the problem in plain language:\n\n```\nMy /api/users endpoint is returning 500. Connect to the process on port 9229,\nset a breakpoint at line 34 of src/routes/users.ts, and tell me what the\ndatabase query result looks like when the error happens.\n```\n\nThe agent will connect, set the breakpoint, wait for the pause, and report back with the actual values — no extra tooling needed.\n\n---\n\n## Make your AI smarter with the skill\n\nThe [`skills/inspector-mcp/SKILL.md`](https://github.com/AbianS/inspector-mcp/blob/main/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.\n\nAdd it to your project so your AI agent picks it up automatically:\n\n```sh\nmkdir -p .claude/skills/inspector-mcp\ncurl -o .claude/skills/inspector-mcp/SKILL.md \\\n  https://raw.githubusercontent.com/AbianS/inspector-mcp/main/skills/inspector-mcp/SKILL.md\n```\n\nOnce in place, your AI will know how to connect, set breakpoints, and inspect variables correctly — without you having to explain it every time.\n\n---\n\n## Available tools\n\n### 🔌 Connection\n\n| Tool | Description |\n|---|---|\n| `debug_connect` | Connect to a Node.js process. Accepts `host`, `port`, and `auto_reconnect`. |\n| `debug_disconnect` | Close a session. |\n| `debug_list_sessions` | List active sessions and their status (`connecting` / `connected` / `paused` / `reconnecting`). |\n\n### 🔴 Breakpoints\n\n| Tool | Description |\n|---|---|\n| `debug_set_breakpoint` | Set a breakpoint on a `.ts` or `.js` file. Supports `condition` for conditional breaks. |\n| `debug_remove_breakpoint` | Remove a breakpoint by its ID. |\n| `debug_list_breakpoints` | List all breakpoints and whether they are verified (will trigger) or not. |\n\n### ▶️ Execution\n\n| Tool | Description |\n|---|---|\n| `debug_continue` | Resume until the next breakpoint. |\n| `debug_pause` | Pause at the next statement. |\n| `debug_step_over` | Next line — skip into function bodies. |\n| `debug_step_into` | Enter the next function call. |\n| `debug_step_out` | Run until the current function returns. |\n\n### 🔍 Inspection _(requires paused session)_\n\n| Tool | Description |\n|---|---|\n| `debug_stack_trace` | Current call stack with TypeScript file paths and line numbers. |\n| `debug_get_variables` | Variables in scope. Use `scope_filter`: `local`, `closure`, `global`, or `all`. |\n| `debug_evaluate` | Evaluate a JS expression in the paused frame. |\n| `debug_get_properties` | Expand a nested object using its `objectId` from `get_variables`. |\n\n### 📋 Console\n\n| Tool | Description |\n|---|---|\n| `debug_read_console` | Read buffered logs. Filter by `level` and `filter` text; paginate with `limit` / `offset`. |\n| `debug_clear_console` | Clear the buffer. |\n\n---\n\n## How it works\n\n```\nYour AI ──(MCP / stdio)──► inspector-mcp ──(CDP / WebSocket)──► node --inspect\n                                  │\n                            source maps\n                           (.ts ↔ .js)\n```\n\n`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.\n\n---\n\n## Troubleshooting\n\n**`ECONNREFUSED` on connect**\n\nThe process is not running with `--inspect`, or is on a different port. Restart with:\n```sh\nnode --inspect src/server.js   # port 9229\nNODE_OPTIONS='--inspect' next dev  # port 9230\n```\n\n**Breakpoint is `verified: false` and never triggers**\n\nSource maps are missing or the compiled file doesn't exist. Run a build first, then check:\n```sh\nls build/server.js.map                # external source map\ngrep sourceMappingURL build/server.js # inline source map\n```\nAs 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.\n\n**`get_variables` / `evaluate` return error `-32600`**\n\nThe session is not paused. These tools only work when the process is stopped at a breakpoint. Verify with `debug_list_sessions` that `status === \"paused\"`.\n\n**Variables show as `[Object]`**\n\n`debug_get_variables` returns shallow previews. Use `debug_get_properties` with the `objectId` to expand nested values.\n\n---\n\n## License\n\nMIT © [Abian Suarez](https://github.com/AbianS)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabians%2Finspector-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabians%2Finspector-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabians%2Finspector-mcp/lists"}