Skip to content
Back to search

mcp-doctor

Zero-dependency TypeScript CLI and library to audit MCP configs and live servers for secrets, tool poisoning, schema bugs, and context-window token tax (with SARIF 2.1.0 output).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pie527645-cloud--mcp-doctor/badge.svg)](/listings/pie527645-cloud--mcp-doctor)

HTML

<a href="/listings/pie527645-cloud--mcp-doctor"><img src="/api/listings/pie527645-cloud--mcp-doctor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 223 lines · 1 finding marked
  1. # @pie527645-cloud/mcp-doctor
  2. Security, prompt-injection, tool-poisoning, configuration, and context-token-tax auditor for **Model Context Protocol (MCP)** servers.
  3. `@pie527645-cloud/mcp-doctor` provides both a zero-runtime-dependency Node.js CLI (`mcp-doctor`) and a typed programmatic library to audit local/IDE MCP configurations and live MCP servers (`stdio` and Streamable HTTP / SSE) before they reach developer workstations or production agents.
  4. ---
  5. ## Features
  6. - **Static Configuration Security (`mcp-doctor scan`)**
  7. - Auto-discovers standard MCP configs across Claude Desktop, Claude Code, Cursor, VS Code (`.vscode/mcp.json`), Antigravity, Windsurf, and project `.mcp.json` files—or audits explicit file/directory paths.
  8. - Detects exposed plaintext credentials (AWS, OpenAI, Anthropic, GitHub, Apify, Stripe, Slack, Bearer tokens, PEM keys, credentialed connection URIs, and high-entropy secrets) with automatic evidence redaction while ignoring dynamic `${ENV_VAR}` placeholders.
  9. - Flags unpinned supply-chain execution (`npx -y`, `@latest`, `bunx`, `uvx`), shell command-injection metacharacters (`&&`, `||`, `|`, `;`, `$(...)`, backticks), shell wrappers (`sh -c`, `cmd /c`), cleartext remote `http://` / `ws://` endpoints, and malformed JSON.
  10. - **Live Protocol & Tool-Poisoning Inspection (`mcp-doctor inspect`)**
  11. - Connects via real MCP JSON-RPC 2.0 (`initialize` -> `notifications/initialized` -> `tools/list`, plus graceful best-effort `resources/list` and `prompts/list`).
  12. - Uses a safe quote-aware argv tokenizer with `spawn(cmd, args, { shell: false })` (never `shell: true`) and clean cross-platform child process termination on exit or timeout.
  13. - Supports Streamable HTTP JSON-RPC (`Accept: application/json, text/event-stream`), SSE response parsing, `Mcp-Session-Id` propagation, and manual redirect SSRF/metadata protection.
  14. - Detects invisible zero-width and BiDi Unicode (`U+200B..U+200F`, `U+202A..U+202E`, `U+2060..U+206F`, `U+FEFF`, `U+E0000..U+E007F`), hidden HTML/XML comments (`<!-- ... -->`), prompt-injection overrides (`ignore previous`, `system prompt`, `disregard`, `you must`, `<IMPORTANT>`, `<instructions>`), credential/file exfiltration (`~/.ssh`, `~/.aws`, `.env`, `/etc/passwd`, `id_rsa`, API key harvesting), and cross-tool shadowing directives.
  15. - Validates tool definitions and JSON Schema `inputSchema` objects, and calculates handshake latency plus per-tool and server-wide **Context Token Tax**.
  16. - **CI-Ready Output Formats & Exit Codes**
  17. - Emits `pretty`, `json`, `markdown`, and **SARIF 2.1.0** compatible with GitHub Code Scanning.
  18. ---
  19. ## Architecture
  20. ```mermaid
  21. flowchart LR
  22. CLI["CLI / Library API"] --> Scan["Config Scanner (scan)"]
  23. CLI --> Inspect["Live Inspector (inspect)"]
  24. Scan --> Auto["Auto-Discovery & Path Walker"]
  25. Auto --> StaticRules["Secret, Supply-Chain, Shell & HTTP Checks (MCP001-MCP006)"]
  26. Inspect --> Stdio["Safe Stdio Client (shell: false)"]
  27. Inspect --> Http["Streamable HTTP + SSE Client (SSRF-Guarded)"]
  28. Stdio --> Analyzer["Tool Poisoning, Schema & Token Analyzer (MCP101-MCP108)"]
  29. Http --> Analyzer
  30. StaticRules --> Report["AuditReport"]
  31. Analyzer --> Report
  32. Report --> Pretty["Pretty Terminal"]
  33. Report --> Json["JSON"]
  34. Report --> Md["Markdown"]
  35. Report --> Sarif["SARIF 2.1.0"]
  36. ```
  37. ---
  38. ## Requirements & Installation
  39. Requires **Node.js >= 20** (tested on Node 20 and Node 22 across Linux and Windows).
  40. ```bash
  41. git clone https://github.com/pie527645-cloud/mcp-doctor.git
  42. cd mcp-doctor
  43. npm install
  44. npm run build
  45. # Run directly from build output
  46. node ./dist/cli.js --help
  47. # Optional: link the local binary into your global PATH as `mcp-doctor`
  48. npm link
  49. mcp-doctor --help
  50. ```
  51. > **Note on Windows PowerShell:** If PowerShell ExecutionPolicy blocks `.ps1` shims, run `npm.cmd install`, `npm.cmd run build`, and `node ./dist/cli.js ...`.
  52. ---
  53. ## CLI Usage
  54. ### 1. Scan MCP Configuration Files
  55. ```bash
  56. # Auto-discover standard IDE and project MCP config files
  57. node ./dist/cli.js scan
  58. # Scan specific files or directories and fail on medium+ severity
  59. node ./dist/cli.js scan ./.mcp.json ./.vscode/mcp.json --fail-on medium
  60. # Emit Markdown summary (useful for $GITHUB_STEP_SUMMARY)
  61. node ./dist/cli.js scan ./configs --format markdown
  62. ```
  63. ### 2. Inspect a Live MCP Server
  64. ```bash
  65. # Inspect a local stdio MCP server safely (quote-aware argv, shell: false)
  66. node ./dist/cli.js inspect --stdio "node ./path/to/mcp-server.js" --timeout 10000 --fail-on high
  67. # Inspect a Streamable HTTP / SSE MCP endpoint and output JSON
  68. node ./dist/cli.js inspect --url "http://127.0.0.1:3000/mcp" --format json
  69. # Generate SARIF 2.1.0 output for GitHub Code Scanning
  70. node ./dist/cli.js inspect --stdio "node ./path/to/mcp-server.js" --format sarif > mcp-audit.sarif
  71. ```
  72. > **Windows `--stdio` Note:** Because `mcp-doctor` spawns child processes with `shell: false` to prevent shell command injection, Windows users inspecting Node-based MCP servers should pass `node <path-to-entry.js>` (or a direct executable path) rather than bare `npx`.
  73. ### Options & Exit Codes
  74. | Flag | Values / Default | Description |
  75. | :--- | :--- | :--- |
  76. | `--stdio "<cmd>"` | string (`inspect` only) | Command line to spawn stdio MCP server (`shell: false`) |
  77. | `--url "<http-url>"` | URL (`inspect` only) | HTTP/HTTPS JSON-RPC / Streamable HTTP MCP endpoint |
  78. | `--timeout <ms>` | integer (default `10000`) | Connection and protocol timeout in milliseconds |
  79. | `--format <fmt>` | `pretty` (default), `json`, `markdown`, `sarif` | Output serialization format |
  80. | `--fail-on <level>` | `high` (default), `critical`, `medium`, `low` | Minimum finding severity that causes exit code `1` |
  81. | Exit Code | Meaning |
  82. | :--- | :--- |
  83. | `0` | Audit completed with zero findings at or above `--fail-on` |
  84. | `1` | Audit completed with one or more findings `>= --fail-on` |
  85. | `2` | Invalid CLI arguments, missing config file, timeout, or unreachable MCP server |
  86. ---
  87. ## Audit Rule Catalog
  88. | Rule ID | Default Severity | Category | Summary |
  89. | :--- | :--- | :--- | :--- |
  90. | `MCP001` | `high` | `config-syntax` | Malformed or unreadable MCP configuration JSON |
  91. | `MCP002` | `critical` | `secrets` | Plaintext API key, token, bearer credential, or high-entropy secret in config |
  92. | `MCP003` | `medium` / `high` | `supply-chain` | Unpinned package runner (`npx -y`, `bunx`, `uvx`, `@latest`) |
  93. | `MCP004` | `high` | `command-injection` | Shell metacharacters (`&&`, `||`, `|`, `;`, `$(...)`, backticks) in server config |
  94. | `MCP005` | `high` | `transport-security` | Cleartext non-localhost `http://` or `ws://` remote MCP endpoint |
  95. | `MCP006` | `medium` | `command-injection` | Inline shell interpreter wrapper (`sh -c`, `bash -c`, `cmd /c`, `powershell -Command`) |
  96. | `MCP101` | `critical` | `tool-poisoning` | Hidden zero-width, BiDi override, or tag Unicode characters in MCP metadata |
  97. | `MCP102` | `high` | `tool-poisoning` | Hidden HTML/XML comment (`<!-- ... -->`) in tool metadata |
  98. | `MCP103` | `critical` | `prompt-injection` | Prompt-injection or override directive (`ignore previous`, `system prompt`, `disregard`, `you must`, `<IMPORTANT>`, `<instructions>`) |
    • Warning: Contains a <important> block, a common wrapper for instructions hidden in a tool description
    • Line 134 on GitHub
  99. | `MCP104` | `critical` | `exfiltration` | Sensitive file or credential exfiltration reference (`~/.ssh`, `~/.aws`, `.env`, `/etc/passwd`, `id_rsa`, API key stealing) |
  100. | `MCP105` | `high` | `tool-shadowing` | Cross-tool shadowing or behavior-hijacking directive |
  101. | `MCP106` | `medium` | `schema-quality` | Invalid or incomplete tool `name`, `description`, or JSON Schema `inputSchema` |
  102. | `MCP107` | `low` | `context-tax` | Single-tool description or schema token bloat |
  103. | `MCP108` | `low` / `medium` | `context-tax` | High total server Context Token Tax across exposed tools |
  104. ---
  105. ## Programmatic API
  106. ```ts
  107. import {
  108. scanConfigs,
  109. inspectServer,
  110. formatReport,
  111. hasFailingFindings,
  112. } from '@pie527645-cloud/mcp-doctor';
  113. // 1. Audit MCP configuration files
  114. const scanReport = await scanConfigs({ paths: ['./.mcp.json'] });
  115. console.log(scanReport.summary);
  116. // 2. Inspect a live MCP server over stdio
  117. const inspectReport = await inspectServer({
  118. stdio: 'node ./dist/mcp-server.js',
  119. timeoutMs: 10_000,
  120. });
  121. console.log(`Context Token Tax: ${inspectReport.inspection?.totalContextTokens} tokens`);
  122. if (hasFailingFindings(inspectReport.findings, 'high')) {
  123. const sarifJson = formatReport(inspectReport, 'sarif');
  124. console.error(sarifJson);
  125. process.exitCode = 1;
  126. }
  127. ```
  128. ---
  129. ## GitHub Actions + SARIF Code Scanning Example
  130. ```yaml
  131. name: MCP Security Audit
  132. on:
  133. push:
  134. branches: [main]
  135. pull_request:
  136. permissions:
  137. contents: read
  138. security-events: write
  139. jobs:
  140. mcp-audit:
  141. runs-on: ubuntu-latest
  142. steps:
  143. - name: Checkout target MCP server repository
  144. uses: actions/checkout@v4
  145. - name: Setup Node.js 22
  146. uses: actions/setup-node@v4
  147. with:
  148. node-version: 22
  149. - name: Build target MCP server
  150. run: npm ci && npm run build
  151. - name: Build @pie527645-cloud/mcp-doctor from source
  152. run: |
  153. git clone --depth 1 https://github.com/pie527645-cloud/mcp-doctor.git /tmp/mcp-doctor
  154. npm --prefix /tmp/mcp-doctor ci
  155. npm --prefix /tmp/mcp-doctor run build
  156. - name: Audit MCP server and emit SARIF 2.1.0
  157. continue-on-error: true
  158. run: node /tmp/mcp-doctor/dist/cli.js inspect --stdio "node ./dist/mcp.js" --format sarif --fail-on high > mcp-doctor.sarif
  159. - name: Upload SARIF to GitHub Code Scanning
  160. uses: github/codeql-action/upload-sarif@v3
  161. with:
  162. sarif_file: mcp-doctor.sarif
  163. ```
  164. ---
  165. ## License
  166. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.