# Mcp Server Fuzzer

> A generic mcp server fuzzer

- **Type:** MCP server
- **Install:** `agentstack add mcp-agent-hellboy-mcp-server-fuzzer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Agent-Hellboy](https://agentstack.voostack.com/s/agent-hellboy)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Agent-Hellboy](https://github.com/Agent-Hellboy)
- **Source:** https://github.com/Agent-Hellboy/mcp-server-fuzzer

## Install

```sh
agentstack add mcp-agent-hellboy-mcp-server-fuzzer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Server Fuzzer

**CLI fuzzing for MCP servers**

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

[](https://github.com/Agent-Hellboy/mcp-server-fuzzer/actions/workflows/lint.yml)
[](https://codecov.io/gh/Agent-Hellboy/mcp-server-fuzzer)
[](https://pypi.org/project/mcp-fuzzer/)
[](https://pepy.tech/projects/mcp-fuzzer)
[](https://modelcontextprotocol.io/specification/2025-11-25/)
[](https://hub.docker.com/r/princekrroshan01/mcp-fuzzer)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)

[Docs Site](https://agent-hellboy.github.io/mcp-server-fuzzer/) • [Getting Started](https://agent-hellboy.github.io/mcp-server-fuzzer/getting-started/getting-started/) • [CLI Reference](https://agent-hellboy.github.io/mcp-server-fuzzer/development/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 `/findings.json`, with per-crash repros under
`/crashes/`, a compact CI summary at
`/run_summary.json`, 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 returned a non-error response to an
  attack-pattern or schema-invalid fuzz input; repeated identical evidence is
  collapsed into one finding with run counts and a response sample
- `performance_outlier` — response time far above the per-target median

`findings.json` is always written for completed sessions, even when no findings
are present (`{"findings": [], "count": 0}`), so CI jobs can assert that report
generation succeeded separately from whether issues were discovered.
`run_summary.json` records whether the run completed or was blocked, plus
tool/protocol counts and run totals for simple CI assertions.

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

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

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

## Quick Start

### 1. Run the bundled HTTP example server

```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

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

### 3. Fuzz protocol requests

```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

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

## Common Commands

```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`](examples/test_server.py)
- an official Go MCP SDK stdio example: [`examples/go_stdio_server`](examples/go_stdio_server)
- an official TypeScript MCP SDK stdio example: [`examples/typescript-stdio-server`](examples/typescript-stdio-server)
- a StreamableHTTP example: [`examples/streamable_http_server.py`](examples/streamable_http_server.py)

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

```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`](examples/README.md).

## Documentation

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

- [Getting Started](https://agent-hellboy.github.io/mcp-server-fuzzer/getting-started/getting-started/)
- [Examples](https://agent-hellboy.github.io/mcp-server-fuzzer/getting-started/examples/)
- [Configuration](https://agent-hellboy.github.io/mcp-server-fuzzer/configuration/configuration/)
- [CLI Reference](https://agent-hellboy.github.io/mcp-server-fuzzer/development/reference/)
- [Safety Guide](https://agent-hellboy.github.io/mcp-server-fuzzer/components/safety/)
- [Architecture](https://agent-hellboy.github.io/mcp-server-fuzzer/architecture/architecture/)
- [Contributing](https://agent-hellboy.github.io/mcp-server-fuzzer/development/contributing/)

## License

MIT. See [`LICENSE`](LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Agent-Hellboy](https://github.com/Agent-Hellboy)
- **Source:** [Agent-Hellboy/mcp-server-fuzzer](https://github.com/Agent-Hellboy/mcp-server-fuzzer)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-agent-hellboy-mcp-server-fuzzer
- Seller: https://agentstack.voostack.com/s/agent-hellboy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.