@turingspark/mcp-debug

A transparent proxy and live dashboard for debugging Model Context Protocol (MCP) servers.

Sits between your MCP host (e.g. Claude Desktop) and any MCP server, intercepting every JSON-RPC message in both directions. All traffic is displayed in a real-time web dashboard and persisted to a local SQLite database.

Quick Start

npx @turingspark/mcp-debug --cmd "node my-mcp-server.js" --open

This starts your MCP server, proxies all stdio traffic, and opens the dashboard at http://localhost:8100.

Use with Claude Desktop

Wrap any existing MCP server in your Claude Desktop config (claude_desktop_config.json):

Before:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["my-mcp-server.js"]
    }
  }
}

After:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": [
        "@turingspark/mcp-debug",
        "--cmd", "node my-mcp-server.js",
        "--open"
      ]
    }
  }
}

Works with any MCP server — Node.js, Python, or any other runtime:

{
  "mcpServers": {
    "python-server": {
      "command": "npx",
      "args": [
        "@turingspark/mcp-debug",
        "--cmd", "python3 my_server.py",
        "--open"
      ]
    }
  }
}

Dashboard Features

The web dashboard at http://localhost:8100 provides:

• Messages — All JSON-RPC requests and responses with full payloads. Click any message to see the complete JSON. Error responses are highlighted with a red ERROR badge.
• Token Estimation — Each message shows an estimated token count (~Tokens column), with a running total in the status bar. Helps you understand the token cost of tool schemas and large responses.
• Request Replay — Click any outbound request, edit the JSON payload, and resend it to the server. Useful for testing parameter changes without restarting your client.
• Timeline — Visual timeline of request/response pairs with latency measurements.
• Stderr — Server stderr output captured in real-time.

The dashboard connects via WebSocket and replays message history, so you can open it at any time without missing earlier traffic.

CLI Options

Usage: mcp-debug [options] [-- <server command> [args...]]

Options:
  --cmd <command>  The MCP server command to proxy (quoted string)
  --port <number>  Dashboard port (default: 8100)
  --db <path>      SQLite database path (default: ~/.mcp-debug/data.db)
  --quiet          Suppress stderr output (default: false)
  --verbose        Print full JSON-RPC messages to stderr (default: false)
  --open           Auto-open dashboard in browser (default: false)
  -h, --help       Display help

Two ways to specify the server command

Use --cmd for simple commands; use -- when your path has spaces or you need shell-free arg splitting.

--cmd (quoted string) — simple, works for most cases:

npx @turingspark/mcp-debug --cmd "node server.js"
npx @turingspark/mcp-debug --cmd "python3 server.py --port 9000"

-- separator — recommended for paths with spaces or complex args:

npx @turingspark/mcp-debug -- node server.js
npx @turingspark/mcp-debug -- python3 "/path/with spaces/server.py"
npx @turingspark/mcp-debug --verbose -- mcp-server-filesystem /my/project

Use -- in Claude Desktop config to keep args clean:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["@turingspark/mcp-debug", "--open", "--", "node", "my-mcp-server.js"]
    }
  }
}

CLI-Only Debugging with --verbose

Use --verbose to print full JSON-RPC messages to stderr — no browser needed. Useful for CI, SSH sessions, or quick debugging:

npx @turingspark/mcp-debug --verbose -- mcp-server-filesystem /tmp/my-project

Each message shows direction, method, latency, and estimated token count:

[mcp-debug] Proxying: mcp-server-filesystem /tmp/my-project
[mcp-debug] Dashboard: http://localhost:8100

[mcp-debug] → initialize id=1 ~40 tokens
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "demo-client", "version": "1.0.0" }
    }
  }
[mcp-debug] ← initialize id=1 [3ms] ~45 tokens
  {
    "result": {
      "protocolVersion": "2024-11-05",
      "capabilities": { "tools": { "listChanged": true } },
      "serverInfo": { "name": "secure-filesystem-server", "version": "0.2.0" }
    }
  }
[mcp-debug] → tools/call id=3 ~33 tokens
  {
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "list_directory",
      "arguments": { "path": "/tmp/my-project" }
    }
  }
[mcp-debug] ← tools/call id=3 [9ms] ~62 tokens
  {
    "result": {
      "content": [{ "type": "text", "text": "[FILE] README.md\n[FILE] index.js" }]
    }
  }

Error responses are flagged with ERROR:

[mcp-debug] ← tools/call (error) id=5 [313ms] ~27 tokens ERROR
  {
    "jsonrpc": "2.0",
    "id": 5,
    "error": {
      "code": -32603,
      "message": "Authentication Failed: Requires authentication"
    }
  }

Debugging Walkthrough

Here's a real example of how mcp-debug helps you find and fix issues.

Catching wrong parameter names

When debugging the Alpaca Trading MCP Server, we called get_stock_snapshot with { "symbol": "AAPL" }. The MCP client showed a generic failure — but the mcp-debug dashboard revealed the actual error:

Error: 1 validation error for get_stock_snapshotArguments
symbol_or_symbols
  Field required [type=missing, input_value={'symbol': 'AAPL'}]

The parameter is symbol_or_symbols, not symbol. Without the debugger, you'd have to dig through the server source code to figure this out.

Spotting token-heavy responses

The tools/list response from a server like mcp-server-github returns ~4,000 tokens of tool schemas on every connection. The ~Tokens column makes this visible immediately — you can see exactly which messages are consuming your context window.

Replaying requests

Found a bug? Click any outbound request in the dashboard, edit the parameters in the JSON editor, and hit Send to replay it. No need to restart your MCP client or re-trigger the conversation.

Tips for Python MCP Servers

• Activate your venv first. If the MCP server is installed in a virtualenv, activate it before running mcp-debug so the server binary is on your PATH:

  source /path/to/venv/bin/activate
  npx @turingspark/mcp-debug --verbose -- my-mcp-server

• Set required environment variables. Many MCP servers need API keys or config via environment variables. Make sure these are exported in the same terminal session before starting the proxy.

• Check for subcommands. Some servers require a subcommand like serve or run. If the server exits immediately with code 1 or 2, check its help output:

  my-mcp-server --help

How It Works

MCP Host (Claude Desktop)
    |
    |  stdin/stdout (JSON-RPC)
    v
mcp-debug proxy
    |  - Intercepts all messages
    |  - Stores in SQLite
    |  - Estimates token usage
    |  - Broadcasts to dashboard via WebSocket
    |
    |  stdin/stdout (JSON-RPC)
    v
MCP Server (your server)

The proxy is fully transparent — it passes all messages through without modification. Your MCP host and server don't know it's there.

Troubleshooting

| Problem | Likely cause | Fix | |---------|-------------|-----| | Server exited with code 1 | Missing API keys or environment variables | Export required env vars before starting | | Server exited with code 2 | Wrong command or subcommand | Check your-server --help for correct usage | | EADDRINUSE on dashboard port | Another instance already running | Kill it with lsof -ti:8100 \| xargs kill or use --port 8101 | | Dashboard shows no messages | Opened before any traffic was sent | Send a request — the dashboard auto-updates via WebSocket | | required option '--cmd' not specified | Using -- but running an older cached version | Run npx @turingspark/mcp-debug@latest to force the latest |

Documentation

For more examples and walkthroughs, visit turingspark.com/tools/mcp-debugger.

License

MIT