mcp-stress

Stress testing tool for MCP (Model Context Protocol) servers.

Install

# npm
npx mcp-stress <command>
npm install -g mcp-stress

# JSR / Deno
deno install -g -A --name mcp-stress jsr:@dgellow/mcp-stress/cli

Commands

run

Execute a stress test against an MCP server.

# Stdio transport (spawns the server)
mcp-stress run -d 30 -c 10 --tool echo -- node my-server.js

# HTTP transport
mcp-stress run -d 30 -c 10 --url http://localhost:3000/mcp

# Find max throughput (auto-scales concurrency)
mcp-stress run -p find-ceiling -d 120 -c 50 -- node my-server.js

# CI mode: JSON output + assertions
mcp-stress run --json --assert "p99 < 500ms" --assert "error_rate < 1%" -- node my-server.js

# Live browser dashboard
mcp-stress run --live -d 60 -c 10 -o results.ndjson -- node my-server.js

# Send exactly N requests (useful for debugging)
mcp-stress run -n 5 -v -- node my-server.js

Options:

| Flag | Description | | ------------------- | --------------------------------------------------------------------------------- | | -p, --profile | Workload profile (default: tool-flood) | | -d, --duration | Test duration in seconds (default: 10) | | -n, --requests | Stop after N requests (overrides duration) | | -c, --concurrency | Peak concurrent workers (default: 1) | | -t, --timeout | Request timeout in ms (default: 30000) | | --tool | Target a specific tool by name | | --shape | Load shape: constant, linear-ramp, exponential, step, spike, sawtooth | | -o, --output | NDJSON output file path | | --live | Open real-time browser dashboard | | --json | Output JSON summary to stdout | | --assert | Threshold assertion, repeatable (e.g. "p99 < 500ms") | | --seed | PRNG seed for reproducibility | | --sse | Use legacy HTTP+SSE transport (default: streamable-http) | | -v, --verbose | Log every request/response |

chart

Generate an interactive HTML report from a previous run.

mcp-stress chart results.ndjson --open

compare

Compare two test runs and detect regressions.

mcp-stress compare baseline.ndjson current.ndjson --open
mcp-stress compare baseline.ndjson current.ndjson --json --assert "p99_delta < 10%"

diagnose

Probe server connectivity and protocol compliance.

mcp-stress diagnose -- node my-server.js
mcp-stress diagnose --url http://localhost:3000/mcp

discover

Enumerate server capabilities (tools, resources, prompts).

mcp-stress discover -- node my-server.js

profiles / shapes

List available workload profiles and load shapes.

mcp-stress profiles
mcp-stress shapes

Transports

• stdio (default): Spawns the server as a subprocess. Use -- command [args].
• Streamable HTTP: Connect to a running server. Use --url.
• SSE (legacy): Use --url with --sse.

Output

All test data is written as NDJSON (newline-delimited JSON) with three event types:

• meta — run parameters and configuration
• request — individual request results (method, latency, ok/error)
• summary — aggregate statistics

Development

./scripts/lint     # Format check + type check
./scripts/test     # Run tests
./scripts/build    # Compile binary + npm packages
./scripts/start    # Run the CLI