mcp-debugger 0.1.1

Transparent proxy to debug, record, validate, and replay MCP (Model Context Protocol) sessions

mcp-debugger

Transparent proxy to debug, record, validate, and replay MCP (Model Context Protocol) sessions.

---

✨ Features

Feature	What it does
🔍 Record	Capture every JSON-RPC message between an MCP client and server
📋 Inspect	Browse messages with syntax-highlighted, formatted terminal output
✅ Validate	Check MCP protocol compliance — handshake order, method names, schemas
🔄 Replay	Regression-test server changes by replaying recorded sessions
📊 Stats	Visualise tool usage, latency trends, and error rates
🔀 Compare	Delta reports between two sessions (latency, errors, tool calls)
📤 Export	JSON, Markdown, or OpenTelemetry (OTLP) traces
⚙️ Config	Persistent user preferences — aliases, timeouts, defaults
🩺 Doctor	Environment diagnostics — Python version, SQLite, Node.js, paths
🚀 Local-first	No cloud, no signup — all data stays on your machine

---

📦 Installation

pip install mcp-debugger

With optional OpenTelemetry (OTLP) export support:

pip install "mcp-debugger[otlp]"

Requirements: Python 3.11+, Node.js (for npx-based MCP servers)

---

🚀 Quickstart

1. Record a session

mcp-debugger proxy \
  --server "npx -y @modelcontextprotocol/server-filesystem /tmp" \
  --name "my-first-session"

Interact with your MCP client (e.g. Claude Desktop). Press Ctrl+C to stop.

2. List recorded sessions

mcp-debugger list

3. Inspect a session

mcp-debugger inspect 1

4. Validate protocol compliance

mcp-debugger validate --server "npx -y @modelcontextprotocol/server-filesystem /tmp"

5. Replay against a new server version

mcp-debugger replay 1 --server "npx -y @modelcontextprotocol/server-filesystem /tmp"

6. Export to Markdown

mcp-debugger export 1 --format markdown --output session-report.md

---

🔧 Use with Claude Desktop

Edit your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "my-filesystem": {
      "command": "mcp-debugger",
      "args": [
        "proxy",
        "--server",
        "npx -y @modelcontextprotocol/server-filesystem /path/to/dir",
        "--name",
        "claude-session"
      ]
    }
  }
}

Every message between Claude and your server is now recorded transparently.

---

📖 Documentation

Document	Description
Command Reference	Every CLI command with all options and examples
Architecture	How it works — components, data flow, sequence diagrams
Tutorials	Step-by-step workflows for common use cases
Configuration	All config keys, defaults, and examples
FAQ	Common questions and troubleshooting
Contributing	Development setup, test structure, PR process
Changelog	Version history

---

🧪 Development Setup

git clone https://github.com/sushant-mutnale/mcp-debugger.git
cd mcp-debugger
python -m venv .venv
source .venv/bin/activate      # Linux/macOS
# or: .venv\Scripts\activate   # Windows
pip install -e ".[dev]"

# Run all tests
pytest

# With coverage
pytest --cov=mcp_debugger --cov-report=term-missing

# Lint and type-check
ruff check .
mypy src/mcp_debugger --ignore-missing-imports

---

🤝 Contributing

See CONTRIBUTING.md for setup instructions, coding style, and pull request process.

---

📄 License

MIT © Sushant Mutnale