How do I install MCP Debug Recorder?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does MCP Debug Recorder need an API key?

The publisher lists these environment variables: DEBUG_RECORDER_DB, LOG_LEVEL, FUZZY_THRESHOLD, DEBUG_RECORDER_REDACT_BEFORE_STORE, HOST, PORT, DEBUG_RECORDER_HTTP_TOKEN, DEBUG_RECORDER_ALLOWED_HOSTS, DEBUG_RECORDER_ALLOWED_ORIGINS, DEBUG_RECORDER_MAX_BODY_BYTES, DEBUG_RECORDER_REMOTE_HTTP.

What transport does MCP Debug Recorder use?

MCP Debug Recorder runs locally over stdio.

When was MCP Debug Recorder last checked?

Last checked 2026-11-10. Record debug sessions, commands, failed attempts, and successful fixes in local SQLite storage.

MCP Debug Recorder MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y [email protected]

Credentials from the publisher

DEBUG_RECORDER_DB — Override the SQLite database location for local debug history.
LOG_LEVEL — Set the minimum structured log level: debug, info, warn, or error.
FUZZY_THRESHOLD — Override the Fuse.js threshold used during fuzzy reranking.
DEBUG_RECORDER_REDACT_BEFORE_STORE — Set to true to redact common secret patterns before persisting debug text.
HOST — HTTP bind host for optional Streamable HTTP mode. Defaults to 127.0.0.1.
PORT — HTTP port for optional Streamable HTTP mode.
DEBUG_RECORDER_HTTP_TOKEN — Bearer token for optional Streamable HTTP mode. Required for non-loopback bind.
DEBUG_RECORDER_ALLOWED_HOSTS — Comma-separated HTTP Host allowlist for optional Streamable HTTP mode.
DEBUG_RECORDER_ALLOWED_ORIGINS — Comma-separated Origin allowlist for optional Streamable HTTP mode.
DEBUG_RECORDER_MAX_BODY_BYTES — Maximum JSON body size for optional Streamable HTTP mode.
DEBUG_RECORDER_REMOTE_HTTP — Must be true to allow optional Streamable HTTP mode to bind outside loopback.

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1DEBUG_RECORDER_DB=<value> LOG_LEVEL=<value> FUZZY_THRESHOLD=<value> DEBUG_RECORDER_REDACT_BEFORE_STORE=<value> HOST=<value> PORT=<value> DEBUG_RECORDER_HTTP_TOKEN=<secret> DEBUG_RECORDER_ALLOWED_HOSTS=<value> DEBUG_RECORDER_ALLOWED_ORIGINS=<value> DEBUG_RECORDER_MAX_BODY_BYTES=<value> DEBUG_RECORDER_REMOTE_HTTP=<value> claude mcp add io.github.oaslananka-debug-recorder-mcp -- npx -y debug-recorder-mcp@1.1.3

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.oaslananka-debug-recorder-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "[email protected]"8      ],9      "env": {10        "DEBUG_RECORDER_DB": "<value>",11        "LOG_LEVEL": "<value>",12        "FUZZY_THRESHOLD": "<value>",13        "DEBUG_RECORDER_REDACT_BEFORE_STORE": "<value>",14        "HOST": "<value>",15        "PORT": "<value>",16        "DEBUG_RECORDER_HTTP_TOKEN": "<secret>",17        "DEBUG_RECORDER_ALLOWED_HOSTS": "<value>",18        "DEBUG_RECORDER_ALLOWED_ORIGINS": "<value>",19        "DEBUG_RECORDER_MAX_BODY_BYTES": "<value>",20        "DEBUG_RECORDER_REMOTE_HTTP": "<value>"21      }22    }23  }24}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

debug-recorder-mcp

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

Tool	Purpose
`start_debug_session`	Start tracking a new issue or incident.
`add_fix`	Record a failed or successful fix attempt.
`record_command`	Save a command, output, exit code, and session link.
`close_session`	Mark a session as resolved or abandoned.
`update_session`	Edit title, description, or tags.
`delete_session`	Permanently delete a session with explicit confirmation.
`search_sessions`	Search history with FTS5, fuzzy reranking, pagination, related groups, and optional Markdown export.
`save_search_preset`	Store a reusable query, filters, and limit.
`list_search_presets`	List saved search presets.
`remove_search_preset`	Remove a saved search preset by name.
`find_similar_errors`	Ask whether a similar error has appeared before.
`get_session`	Fetch full details, fixes, and commands.
`get_session_context`	Get an AI-friendly session summary.
`list_sessions`	Browse sessions with filters.
`get_stats`	Summarize debug history.
`get_diagnostics`	Return a redacted operational diagnostics snapshot.
`export_sessions`	Export a full JSON backup or a lightweight summary inventory.
`import_sessions`	Import a validated export payload.

Real usage examples

Have I seen this before?

Ask your MCP client:

I am getting TypeError: Cannot read properties of undefined. Have I seen this before?

The client can call find_similar_errors, then inspect the best match with get_session_context.

Record an active incident

Call start_debug_session with the problem title and error details.
Add terminal commands with record_command.
Add each attempted fix with add_fix.
Improve title, notes, or tags with update_session.
Close the incident with close_session.

Back up or migrate history

Call export_sessions with format: "json". The response is marked with format: "json" and contains the full sessions, fixes, and commands arrays.
Store the returned object in your backup system.
Restore later by passing that object as import_sessions.payload.

For a lightweight inventory, call export_sessions with format: "summary". Summary responses are marked with format: "summary", include aggregate stats and abbreviated session rows, and are not restore payloads.

HTTP transport

The package also supports local Streamable HTTP:

npm run start:http

Useful routes:

GET /health
GET /version
MCP endpoint: POST /mcp

HTTP mode is local-first by default. It binds to 127.0.0.1, creates an isolated stateless MCP server/transport per request, validates Host, validates browser Origin when present, and enforces a JSON body-size limit before the MCP transport receives the request.

For deliberate non-loopback exposure, set all of these:

HOST=0.0.0.0
DEBUG_RECORDER_REMOTE_HTTP=true
DEBUG_RECORDER_HTTP_TOKEN=replace-with-a-long-random-token
DEBUG_RECORDER_ALLOWED_HOSTS=debug-recorder.example.com
DEBUG_RECORDER_ALLOWED_ORIGINS=https://debug-recorder.example.com
npm run start:http

Wildcard origins are rejected for remote mode. The static bearer token is private/shared-secret mode: every caller shares one identity, one authority level, and one SQLite dataset. It is suitable for loopback, an encrypted trusted network, or a private authenticating proxy, but it is not OAuth and does not provide per-user scopes or revocation.

Public multi-user HTTP is not supported by the current release. The accepted target architecture uses an external authorization server and MCP-aware gateway with protected-resource discovery, audience-bound tokens, scopes, rate limits, audit events, and subject-aware storage. See Public HTTP authorization and ADR-0006.

Configuration

Variable	Description
`DEBUG_RECORDER_DB`	Override the SQLite database path.
`HOST`	HTTP bind host. Defaults to `127.0.0.1`.
`PORT`	HTTP port. Defaults to `3000`.
`DEBUG_RECORDER_HTTP_TOKEN`	Private/shared-secret token; required for non-loopback HTTP, not OAuth.
`DEBUG_RECORDER_ALLOWED_HOSTS`	Comma-separated HTTP `Host` allowlist.
`DEBUG_RECORDER_ALLOWED_ORIGINS`	Comma-separated browser `Origin` allowlist.
`DEBUG_RECORDER_MAX_BODY_BYTES`	HTTP JSON body limit. Defaults to `1048576`.
`DEBUG_RECORDER_REMOTE_HTTP`	Enable non-loopback HTTP with `true`, `1`, or `yes`.
`DEBUG_RECORDER_REDACT_BEFORE_STORE`	Enable pre-store redaction with `true`, `1`, or `yes`.
`LOG_LEVEL`	Minimum structured log level: `debug`, `info`, `warn`, or `error`.
`FUZZY_THRESHOLD`	Override the Fuse.js reranking threshold.

Boolean configuration also accepts false, 0, and no; values are case-insensitive, whitespace is ignored, and unsupported values fail fast. Diagnostics reports the resolved effective values rather than re-reading changed environment strings.

Data and privacy

Database: local SQLite via better-sqlite3.
Search index: SQLite FTS5 virtual table.
Default path: ~/.debug-recorder-mcp/sessions.db.
Redaction: optional before-store redaction plus diagnostics redaction.
Deletion: destructive operations require explicit confirmation.
Maintenance: see Storage retention and maintenance.

better-sqlite3 uses a native addon. If Node versions change and bindings fail, run npm rebuild better-sqlite3.

Docker

docker build -t debug-recorder-mcp:local .
docker run --rm -p 127.0.0.1:3000:3000 \
  -e HOST=0.0.0.0 \
  -e DEBUG_RECORDER_REMOTE_HTTP=true \
  -e DEBUG_RECORDER_HTTP_TOKEN=replace-with-a-long-random-token \
  -e DEBUG_RECORDER_ALLOWED_HOSTS=127.0.0.1:3000,localhost:3000 \
  -e DEBUG_RECORDER_ALLOWED_ORIGINS=http://127.0.0.1:3000,http://localhost:3000 \
  debug-recorder-mcp:local

The image installs with npm ci, preserves reviewed native install scripts, prunes development dependencies, and runs as the non-root node user.

Documentation

Published documentation is generated by npm run docs:site and published to GitHub Pages:

https://oaslananka.github.io/debug-recorder-mcp/

Important docs:

Development

npm ci
npm run format:check
npm run lint
npm run check:dead-code
npm run test:coverage
npm run test:fuzz
npm run build
npm run test:e2e
npm run audit
npm run check:install-scripts
npm pack --dry-run
npm run check:package-size
npm run check:version
npm run check:mcp
npm run check:security-policy
npm run check:sbom
npm run docs:site

Full local gate:

npm run ci:local

Release readiness:

npm run prepublishOnly
npm run check:mcp-registry

Release and npm publishing

The normal release workflow uses Release Please, builds release assets, generates SBOM/checksums, attests the tarball, uploads GitHub Release assets, and publishes to npm with provenance.

For the first npm package creation, use the manual Initial npm Token Publish workflow with repository secret NPM_TOKEN. After the package exists and npm trusted publishing is configured, the regular Release workflow can publish through GitHub OIDC. Details are in Release flow.

License

Released under the MIT License. package.json also declares "license": "MIT", and the npm package includes LICENSE.

Funding

If this project saves you debugging time, support development here:

Buy Me a Coffee: https://www.buymeacoffee.com/oaslananka
GitHub Sponsors: https://github.com/sponsors/oaslananka

Funding metadata is available in both .github/FUNDING.yml and package.json.

Agent plugin and runtime configuration

This repository owns the product-level agent plugin, MCP runtime configuration, and product-specific skills for debug-recorder-mcp. The central agent-tools repository should catalog this plugin, but the manifest and workflow instructions live here so they stay synchronized with the actual MCP server package.

File	Purpose
`.claude-plugin/plugin.json`	Claude Code-valid product plugin manifest.
`.mcp.json`	Claude Code project-local MCP server configuration.
`.codex/config.example.toml`	Codex CLI MCP configuration example.
`.vscode/mcp.example.json`	VS Code / GitHub Copilot workspace MCP configuration example.
`opencode.example.jsonc`	OpenCode project MCP configuration example.
`.opencode/skills/`	OpenCode-native mirrored skill definitions.
`docs/agent-runtime-config.md`	Agent runtime setup and validation notes.

Validate plugin packaging locally:

claude plugin validate .