MCP Debugger CLI 🛠️

Fuzz, validate, and debug any MCP (Model Context Protocol) stdio server.

MCP servers communicate via stdin/stdout JSON-RPC. A single console.log() buried in your server code can corrupt the protocol stream — causing silent failures, hallucinated tool calls, and hours of debugging. The MCP Debugger CLI catches these issues before they reach production.

The Problem

When an MCP server accidentally writes to stdout (console.log, stray print(), debug output):

• JSON-RPC corruption: Non-JSON lines mixed into the response stream
• Client crashes: Parsers fail on unexpected output
• Silent failures: Tools appear to work but return garbled data
• Hours of debugging: The error isn't in your MCP logic — it's in a forgotten console.log("got here")

What This Tool Does

1. Standard probes — Runs init + tools/list handshake, validates all responses are clean JSON-RPC
2. Fuzz testing — Sends edge-case inputs (truncated JSON, unicode bombs, binary noise) to test server robustness
3. Response validation — Detects any non-JSON-RPC lines in server output
4. JSON output — Machine-readable reports for CI/CD integration

Quick Start

# Install (one-liner)
curl -fsSL https://raw.githubusercontent.com/hermes-ai/mcp-debugger/main/workflows/install.sh | bash

# Run against any MCP server
mcp-debugger --command "npx @modelcontextprotocol/server-filesystem /tmp"

# Run with fuzz testing
mcp-debugger --command "python3 my_mcp_server.py" --fuzz

# Full verbose report
mcp-debugger --command "node server.js" --fuzz --cycles 50 --verbose

Installation

Option 1: One-liner (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/hermes-ai/mcp-debugger/main/workflows/install.sh | bash

Option 2: Manual

git clone https://github.com/hermes-ai/mcp-debugger.git
cd mcp-debugger
chmod +x src/mcp-debugger
sudo ln -s "$PWD/src/mcp-debugger" /usr/local/bin/mcp-debugger

Usage

# Basic usage — test an MCP server
mcp-debugger -c "npx @modelcontextprotocol/server-filesystem /tmp"

# Run fuzz tests (edge-case inputs)
mcp-debugger -c "python3 my_server.py" -f

# Detailed output
mcp-debugger -c "node server.js" -f -v

# JSON output for CI integration
mcp-debugger -c "uvx my-mcp-server" --json

# Help
mcp-debugger --help

Example Output

── MCP Debugger :: npx @modelcontextprotocol/server-filesystem /tmp ──

[INFO] Running standard MCP handshake probes...
[OK]   initialize: clean (1.23s)
[OK]   tools/list: clean (0.89s)

── Fuzz Testing ──
[OK]   Fuzz #1: CLEAN (0.45s)
[WARN] Fuzz #2: CORRUPTED — 1 bad lines
        Line 3: console.log('debug info')
[OK]   Fuzz #3: CLEAN (0.51s)

── Summary ──
[ERR]  1 issue(s) detected:
        ✗ Fuzz testing: 1/10 inputs caused corruption
  Health: UNSTABLE

MCP Config Template

Add the debugger as a client in your MCP config to periodically health-check your servers:

{
  "mcpServers": {
    "mcp-debugger": {
      "command": "mcp-debugger",
      "args": ["--command", "python3 /path/to/my_server.py", "--fuzz", "--cycles", "5", "--json"],
      "env": {}
    }
  }
}

Use Cases

For MCP Server Developers

• Pre-commit hook: Run mcp-debugger before git commit to catch stdio corruption early
• CI pipeline: Use --json output in GitHub Actions to gate deployments
• Regression testing: Fuzz the server after every change

For MCP Client/Tool Developers

• Audit third-party servers: Quickly assess reliability before integrating
• Debug integration issues: Is the server broken or your client?
• Validate configurations: Test server-config combinations programmatically

Requirements

• Python 3.8+
• The target MCP server must be invocable via a shell command

Common Issues Detected

Issue	Symptom	Detection Method
console.log() debug statements	Line "console.log(...)" in stdout	Standard probes
print() in Python servers	Random text in JSON stream	Standard probes
Stderr redirect to stdout	Error messages in response	Fuzz testing
Truncated responses	Incomplete JSON	Fuzz testing
Unicode handling bugs	Server crashes on special chars	Fuzz testing
Binary output corruption	Null bytes or control chars	Fuzz testing

Roadmap

• Standard MCP handshake probes
• Fuzz testing with edge-case inputs
• JSON output for CI/CD
• Latency benchmarking (req/s, p50/p95/p99)
• Memory leak detection after N cycles
• MCP inspector mode (interactive debugging)
• VS Code extension

License

MIT — Free for all use. If this saves you a debugging session, consider supporting the project.

Support

If the MCP Debugger CLI saves you time, please:

• ⭐ Star the repo on GitHub
• 🐛 Report issues you find
• 💛 Support the project (₹99, pay-what-you-want)