mcp-debugger

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

✨ Features

📦 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

🧪 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