debug-recorder-mcp

debug-recorder-mcp

Local-first debug memory for MCP clients.
Record incidents, commands, failed attempts, successful fixes, diagnostics, and searchable debugging history in SQLite.

Published docs · Usage · Client recipes · Security · Release flow

Why this exists

Debugging knowledge usually disappears into chat windows, terminals, and commit history. debug-recorder-mcp gives MCP-enabled agents and IDEs a durable local memory so they can answer:

“Have I fixed this before?”

It stores each debugging session, error, command, attempted fix, working fix, tags, and context in a local SQLite database. Search combines SQLite FTS5 with fuzzy reranking, reusable presets, pagination metadata, related-session groups, and optional Markdown exports.

Highlights

• Local-first storage: no external database or hosted service required.
• MCP-native tools: stdio server for desktop MCP clients plus optional Streamable HTTP mode.
• Search that survives messy errors: FTS5 + Fuse.js reranking for stack traces, typos, Unicode, and punctuation-heavy logs.
• Reusable search presets: save common filters and limits for recurring incident patterns.
• Safe operations: redaction-before-store option, explicit destructive confirmations, local HTTP host/origin/auth/body-limit hardening.
• Diagnostics: get_diagnostics returns redacted runtime, schema, package, and health signals for support without leaking raw paths, tokens, stack traces, or command output.
• Release-grade packaging: audit, coverage, fuzzing, package-size gates, SBOM/VEX policy, install-script approvals, provenance-ready release workflow, and MCP Registry readiness checks.

Quick start

Requires Node.js 22 LTS or 24 LTS and npm 10+.

npx debug-recorder-mcp

Default database path:

~/.debug-recorder-mcp/sessions.db

Use a custom database path:

DEBUG_RECORDER_DB=/path/to/custom.db npx debug-recorder-mcp

MCP client setup

Desktop MCP clients

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

VS Code / GitHub Copilot

Create or update .vscode/mcp.json:

{
  "servers": {
    "debug-recorder-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["debug-recorder-mcp"]
    }
  }
}

More setup examples are in Client setup recipes.

Available MCP tools