mcp-fuzzer 0.3.3

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.

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

python3 examples/test_server.py

That server listens on http://localhost:8000 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 --runs 10

3. Fuzz protocol requests

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

4. Run tools and protocol together

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

Common Commands

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

# Export results
mcp-fuzzer --mode tools --protocol http --endpoint http://localhost:8000 \
  --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 \
  --auth-config examples/auth_config.json

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

Example Servers

This repository bundles:

• an HTTP example server: examples/test_server.py
• a StreamableHTTP example: examples/streamable_http_server.py

It does not currently bundle a stdio example server. For 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.