Mcp Server Fuzzer

What is Mcp Server Fuzzer about?

Mcp Server Fuzzer is a command‑line utility that aggressively tests MCP servers by generating random inputs for tool calls, protocol messages, and resource flows. It works over HTTP, SSE, stdio, and StreamableHTTP transports and can enforce sandboxing, filesystem restrictions, and network limits to keep local testing safe.

How to use Mcp Server Fuzzer?

1. Install –

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

   Docker alternative:

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

2. Start an MCP server (example provided):

   pip install "mcp[cli]" uvicorn
   python3 examples/test_server.py   # listens on http://localhost:8000/mcp/
   

3. Run fuzzing – choose mode, protocol, endpoint, and runs:

   mcp-fuzzer --mode tools --protocol http --endpoint http://localhost:8000/mcp/ --runs 10
   mcp-fuzzer --mode protocol --protocol-type InitializeRequest --protocol http \
               --endpoint http://localhost:8000/mcp/ --runs-per-type 5
   mcp-fuzzer --mode all --phase both --protocol http --endpoint http://localhost:8000/mcp/
   

   Additional flags enable safety reporting, export results (CSV/HTML), authentication, or load a YAML config via --config.

Key Features

• Multi‑mode fuzzing: target tools, protocol messages, or both.
• Transport support: HTTP, SSE, stdio, StreamableHTTP.
• Safety system: filesystem sandbox, PATH command blocking, network restrictions, optional safety reports.
• Rich output: console summary, CSV/HTML exports, detailed logs.
• Extensible configuration: YAML/JSON files for auth, safety settings, and custom runs.
• Docker image: ready‑to‑run without local Python setup.
• Built‑in example servers in Python, Go, and TypeScript for quick demos.

Use Cases

• Security research – discover crash bugs, injection vectors, or protocol violations in MCP implementations.
• Continuous integration – add fuzzing as a CI step to validate new server releases.
• Compliance testing – verify adherence to the MCP specification (e.g., 2025‑11‑25).
• Tool development – stress‑test custom MCP tools before publishing.
• Educational demos – illustrate fuzzing techniques for developers learning MCP.

FAQ

Q: Which Python version is required? A: Python 3.10 or newer.

Q: Can I fuzz a server that runs locally via stdio? A: Yes. Use --protocol stdio and supply the command as the endpoint, e.g., --endpoint "python my_server.py".

Q: How do I limit filesystem access? A: Enable the safety system with --enable-safety-system and optionally set --fs-root /tmp/mcp-safe.

Q: Where are the results stored? A: Use --export-csv <file> or --export-html <file> to generate reports. Without export flags, a summary is printed to stdout.

Q: Is there support for authentication? A: Yes. Provide a JSON auth config via --auth-config to supply headers or tokens for protected tools.

Q: Can I run the fuzzer inside CI pipelines? A: Absolutely. The CLI works non‑interactively and can be invoked with a YAML config file to define deterministic runs.

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

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.