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+.

hljs language-bash

# 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:

hljs language-bash

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

Quick Start

1. Run the bundled HTTP example server

hljs language-bash

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

hljs language-bash

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

3. Fuzz protocol requests

hljs language-bash

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

4. Run tools and protocol together

hljs language-bash

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

Common Commands

hljs language-bash

# 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:

hljs language-bash

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:

License

MIT. See LICENSE.

mcp-server-fuzzer

MCP Server Fuzzer

What It Does

Install

Quick Start

1. Run the bundled HTTP example server

2. Fuzz tools

3. Fuzz protocol requests

4. Run tools and protocol together

Common Commands

Example Servers

Documentation

License

Similar Packages

Tags

Original Author

Publisher