mcp-fuzzer 0.4.0

MCP server fuzzer client and utilities

MCP Server Fuzzer

CLI fuzzing for MCP servers

Tool fuzzing • Protocol fuzzing • HTTP/SSE/stdio/StreamableHTTP • Safety controls • Rich reporting

Docs Site • Getting Started • CLI Reference

What It Does

MCP Server Fuzzer tests MCP servers by fuzzing:

• tool arguments
• protocol request types
• resource and prompt request flows
• multiple transports: http, sse, stdio, and streamablehttp

It includes optional safety controls such as filesystem sandboxing, PATH-based command blocking, and network restrictions for safer local testing.

Findings It Reports

Beyond protocol/transport errors, runs are classified into categorized findings (written to <output-dir>/findings.json, with per-crash repros under <output-dir>/crashes/, and summarized on stdout):

• crash — server process terminated abnormally (segfault/abort/panic or non-zero exit); captures the signal and a stderr tail
• auth_bypass — a protected tool answered an unauthenticated call
• injection_reflection — a dangerous input token was echoed back verbatim
• oversized_response — response exceeded the read cap (resource exhaustion)
• hang — request timed out (deadlock / infinite loop / ReDoS)
• internal_error — JSON-RPC -32603 (unhandled server-side exception)
• error_leakage — stack trace / panic leaked in output
• memory_growth — server RSS grew multi-fold across runs (stdio targets)
• non_determinism — identical input produced differing outcomes
• accepted_malformed — server accepted clearly-invalid input without error
• performance_outlier — response time far above the per-target median

Tip: for compiled-language servers (Go/C/C++/Rust), run the target under a sanitizer or race build so memory bugs surface as observable crashes.

Install

Requires Python 3.10+.

# PyPI
pip install mcp-fuzzer

# From source
git clone --recursive https://github.com/Agent-Hellboy/mcp-server-fuzzer.git
cd mcp-server-fuzzer
pip install -e .

Docker is also supported:

docker build -t mcp-fuzzer:latest .
docker run --rm mcp-fuzzer:latest --help

Quick Start

1. Run the bundled HTTP example server

pip install "mcp[cli]" uvicorn
python3 examples/test_server.py

That server uses the official Python MCP SDK, listens on http://localhost:8000/mcp/, and exposes:

• test_tool
• echo_tool
• secure_tool requiring Authorization: Bearer secret123

2. Fuzz tools

mcp-fuzzer --mode tools --protocol http --endpoint http://localhost:8000/mcp/ --runs 10

3. Fuzz protocol requests

mcp-fuzzer --mode protocol --protocol-type InitializeRequest \
  --protocol http --endpoint http://localhost:8000/mcp/ --runs-per-type 5

4. Run tools and protocol together

mcp-fuzzer --mode all --phase both --protocol http --endpoint http://localhost:8000/mcp/

Common Commands

# Enable command blocking + safety reporting
mcp-fuzzer --mode tools --protocol http --endpoint http://localhost:8000/mcp/ \
  --enable-safety-system --safety-report

# Export results
mcp-fuzzer --mode tools --protocol http --endpoint http://localhost:8000/mcp/ \
  --export-csv results.csv --export-html results.html

# Use auth config for the bundled secure_tool example
mcp-fuzzer --mode tools --protocol http --endpoint http://localhost:8000/mcp/ \
  --auth-config examples/auth_config.json

# Load settings from YAML
mcp-fuzzer --config config.yaml

Example Servers

This repository bundles:

• an official Python MCP SDK HTTP example: examples/test_server.py
• an official Go MCP SDK stdio example: examples/go_stdio_server
• an official TypeScript MCP SDK stdio example: examples/typescript-stdio-server
• a StreamableHTTP example: examples/streamable_http_server.py

For other stdio usage, point the fuzzer at your own server:

mcp-fuzzer --mode tools --protocol stdio --endpoint "python my_server.py" \
  --enable-safety-system --fs-root /tmp/mcp-safe

More runnable example flows are documented in examples/README.md.

Documentation

Keep the README for the basics. Use the docs for everything else:

• Getting Started
• Examples
• Configuration
• CLI Reference
• Safety Guide
• Architecture
• Contributing

License

MIT. See LICENSE.