Content
# crowd-test-mcp 🔥
**The mob, on tap — an MCP server for [crowd-test](https://github.com/anhhuyn411-alt/crowd-test).**
Ask Claude Desktop, Claude Code, Cursor, or any MCP client to unleash a crowd
of AI virtual users — impatient shoppers, confused seniors, keyboard-only
users, chaos monkeys — on your website. They browse it in real Chromium,
file findings, and hand back a damage report with a **survival grade** (S–F).
> *"Send the mob at https://staging.myapp.com and tell me what to fix first."*
That's the whole workflow now.
## Install
```bash
pip install crowd-test-mcp
```
An LLM key is required in the server's environment: `ANTHROPIC_API_KEY` or
`OPENAI_API_KEY`.
### Claude Code
```bash
claude mcp add crowd-test -e ANTHROPIC_API_KEY=sk-... -- crowd-test-mcp
```
### Claude Desktop / Cursor / anything MCP
```json
{
"mcpServers": {
"crowd-test": {
"command": "crowd-test-mcp",
"env": { "ANTHROPIC_API_KEY": "sk-..." }
}
}
}
```
## Tools
| Tool | What it does |
|---|---|
| `run_crowd_test` | Send the crowd at a URL. Pick personas, add a random `mob`, set a `goal`, choose the verification depth (`none` / `detective` / `cross` / `tribunal`). Returns a compact damage summary; full markdown/HTML reports land in `~/crowd-test-reports/`. |
| `list_personas` | The ten built-in ringleaders and what each one catches. |
| `preview_mob` | Preview the random mob a given `count`/`seed` would generate. |
| `read_report` | Fetch the newest full markdown report from disk. |
## The verification tribunal
Findings can be cross-examined by up to three independent harnesses before
they count against the grade — a skeptical detective agent, a raw Playwright
probe, and a [Microsoft Webwright](https://github.com/microsoft/Webwright)
agent. Automation artifacts get disputed instead of panicking you. Details in
the [crowd-test README](https://github.com/anhhuyn411-alt/crowd-test#the-tribunal-%EF%B8%8F).
Deeper layers need one-time extras:
```bash
pip install crowd-test[probe] && playwright install chromium # verify="cross"
pip install git+https://github.com/microsoft/Webwright # verify="tribunal"
```
## Good to know
- **Runs take minutes, not seconds** — every persona drives a real browser.
Start with 2–3 personas; escalate to `mob=10` when you mean it.
- **Only test what you own.** The mob is for your own staging and production
sites, not other people's.
- Reports default to `~/crowd-test-reports/<host>-<timestamp>/`.
## License
[MIT](LICENSE)
