Connect any LLM — local Ollama or cloud Claude / GPT / Gemini — to MCP servers, break them with 23 real, runnable exploits, then harden them with a reusable guardrails library. All from a polished desktop console the CLI.
Power your agent
Install from the publisher. Not a PlugMCP endpoint.
Host a copy with our keys and logs.
No packaged release in the registry yet. Follow the repository README.
Remote URL or a command on your machine? How the two installs differ
Run on PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LaunchFrom the publisher
Connect any LLM — local Ollama or cloud Claude / GPT / Gemini — to MCP servers, break them with 23 real, runnable exploits, then harden them with a reusable guardrails library. All from a polished desktop console the CLI.
A purple-team lab for the Model Context Protocol (MCP): build, attack, and defend MCP servers with local + cloud LLMs — with a native desktop GUI.
PurpleMCP teaches the full lifecycle of the Model Context Protocol — the open standard that lets AI models call real tools. It does three things, and the third is what makes it purple (red team + blue team together):
[!WARNING] The
attacks/folder contains intentionally vulnerable code for security education. It only runs onlocalhost, refuses to start without an explicit opt-in flag, and "exfiltrates" only to a fake local sink. Read ETHICS.md before using it. Only test systems you own.
[!TIP] New to MCP security? Start here → The MCP Security Handbook — a complete, in-depth guide to the protocol, the 23 attack classes, and the 18 guardrails that stop them. (Also readable in-app via the Learn page.)
The whole teaching method is show, don't tell — you watch the attack land, then watch the defense stop it, with the real technical output streaming live. Every lab also has a manual terminal: the exact commands behind each demo, ready to copy into your own shell or run in place.
The Model Context Protocol is an open standard (think "USB-C for AI tools"). An MCP server exposes tools, resources, and prompts. An MCP host (the thing running the model) connects to those servers and lets the model call the tools. So instead of an LLM that can only talk, you get one that can read files, hit APIs, query databases — whatever the servers expose. That power is exactly why the security story matters: every tool is a new way in.
LOCAL CLOUD
┌─────────┐ ┌───────────────────────────────────┐
│ Ollama │ │ Claude · GPT · Gemini · OpenRouter │ ← bring your own key
└────┬────┘ └─────────────────┬─────────────────┘
│ │
└───────────┬──────────────┘
▼
┌──────────────────────────────┐
│ PurpleMCP Host │ purplemcp/
│ providers/ → one interface │ • normalizes tool-calling across LLMs
│ host/agent → the loop │ • discovers tools, runs the call loop
└───────────────┬──────────────┘
│ MCP (stdio / streamable-http)
┌───────────────┼───────────────────────────────┐
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌─────────────┐
│ servers/ │ │ attacks/ ⚠│ │ defense/ │
│ (clean) │ │(vulnerable)│ ───── fix ────▶ │ (hardened) │
└───────────┘ └───────────┘ └─────────────┘
The same host can point at a clean server, a vulnerable one, or its hardened twin — that side-by-side is the whole teaching method.
Prerequisites: Python 3.11+, and Ollama if you want local models
(you already have it if ollama --version works).
# 1. Install PurpleMCP (editable, so edits take effect immediately)
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[gui]" # include the desktop GUI; use `pip install -e .` for CLI-only
# 2. Configure keys (only the providers you want; Ollama needs none)
cp .env.example .env # then edit .env
# 3. Pull a TOOL-CAPABLE local model (skip if you only use cloud)
ollama pull qwen2.5 # the default; reliably does structured tool calls
# 4. Launch the desktop app — drive everything from here
purplemcp gui
[!IMPORTANT] Use a model that actually calls tools. Every feature here (the agent, the Chat Playground, the benchmark's model probe) needs structured tool-calling.
qwen2.5is the default and does this reliably.llama3.1chats fine but often just narrates a JSON blob describing a call instead of making one — so the tools never run and the Chat Playground looks broken. If chat "does nothing," that's almost always the model: switch toqwen2.5. (See docs/03-installing-models.md.)
Prefer the terminal? The same core powers a full CLI:
purplemcp providers # which LLMs are configured/ready
purplemcp servers # which MCP servers are registered
purplemcp tools --server calculator # list a server's tools
purplemcp ask "what is 19% of 4,200 plus the square root of 144?" -s calculator
purplemcp chat -s calculator -s notes # interactive, multi-server chat
Want Claude/GPT instead of local? Put the key in .env and add --provider anthropic (or openai,
gemini, openrouter).
purplemcp gui opens a native, dark purple-team security console (PySide6) over the exact same core
the CLI uses — no separate server, no browser. It organizes all of PurpleMCP into clear sections:
[!NOTE] The manual terminal lives in both labs. Each exploit/defense lists the exact
purplemcp …/python …commands behind it — every one copyable (paste into your own shell) and runnable in place, with real subprocess output streaming into a colourised console. It's deliberately scoped to the project's own commands, so it stays a teaching tool, not an arbitrary shell.
Throughout, a ⌘K command palette jumps to any page or action, ⌘1–9 switch pages, and a status bar shows lab state, live async activity, and the default model.
The Attack Lab and Defense Lab only launch intentionally-vulnerable servers after you explicitly arm the lab in the UI — the same opt-in friction as the CLI lab flag. See docs/06-gui.md for a full tour, and ETHICS.md.
pip install -e ".[gui]" # one-time: pull in PySide6
purplemcp gui # or: python -m purplemcp.gui
purplemcp/ CORE package (installable)
providers/ one uniform interface over Ollama/Anthropic/OpenAI/Gemini/OpenRouter
host/ MCP client manager + the agent tool-calling loop
installer/ wire MCP servers into Claude Desktop & other hosts
guardrails/ the reusable hardening library (used by defense/)
gui/ the PySide6 desktop app (`purplemcp gui`)
scanner.py static + dynamic MCP security analyzer
cli.py the `purplemcp` command
servers/ CLEAN, safe-by-default example MCP servers
attacks/ ⚠️ LAB-ONLY vulnerable servers + exploits (see ETHICS.md)
defense/ hardened twins, the security playbook + checklist, scanner docs
docs/ deep dives: what-is-mcp, architecture, installing models,
the attack catalog, the defense playbook, and the GUI tour
tests/ pytest suite that proves the guardrails block the attacks
The core idea: one host, any model, any server. Each provider is a small adapter implementing the
same interface, so the tool-calling loop in purplemcp/host/agent.py doesn't
care whether it's driving a local Llama or cloud Claude.
purplemcp providers # readiness of each LLM
purplemcp tools --server filesystem # introspect a server
purplemcp call --server calculator --tool add --args '{"a":2,"b":3}' # call a tool directly, no LLM
purplemcp ask "summarize my notes" --provider openai --server notes
purplemcp install claude-desktop --server calculator # add to Claude Desktop config
Twenty-three self-contained modules, each a vulnerable server + an exploit + a writeup:
Full catalog with mechanics: docs/04-attack-catalog.md. Each lives in
attacks/NN_*/ and is gated by the safety switch.
Every attack above has a hardened twin in defense/ that imports the reusable primitives
in purplemcp/guardrails/:
Prove it yourself, side by side — exploited on the left, blocked on the right:
export PURPLEMCP_LAB_ENABLED="i-understand-this-is-a-lab"
python defense/compare.py # every case, red vs blue
python defense/compare.py ping # just one (matches the tool/title)
And a scanner that flags risky MCP servers before you ever run them:
purplemcp scan attacks/03_command_injection/vulnerable_server.py # static analysis
purplemcp scan --server calculator # live tool inspection
Playbook: docs/05-defense-playbook.md · Checklist: defense/checklist.md.
PurpleMCP is built to be a reproducible research artifact, not just a demo:
purplemcp/taxonomy.py. Browse the full table in
docs/TAXONOMY.md or run purplemcp taxonomy.purplemcp bench measures guardrail effectiveness (deterministic: attack vs
vulnerable vs hardened twin) and, optionally, model susceptibility (--provider), writing JSON +
Markdown to results/. A committed reference run is in
results/guardrail-benchmark.md (17/17 cases fixed by the hardened
twins).purplemcp scan <path> --format sarif emits SARIF 2.1.0 for GitHub code scanning /
any SAST UI.purplemcp report stitches the taxonomy, a static scan of the lab's own code, and
the guardrail inventory into one Markdown artifact (docs/SECURITY-REPORT.md)..github/workflows/ci.yml runs the test suite + benchmark on
3.11/3.12 and uploads the scan as SARIF on every push.CITATION.cff and the full write-up in
docs/07-research-methodology.md.purplemcp bench # deterministic guardrail benchmark
purplemcp bench --provider ollama -m qwen2.5 # + model-susceptibility probe
purplemcp scan attacks --format sarif -o purplemcp.sarif
purplemcp tools / ask / chat.purplemcp scan at both and compare findings.attacks/ code is intentionally vulnerable by design; to report a real
issue in the framework itself, see SECURITY.md.MIT — see LICENSE. This project includes intentionally vulnerable software for education; the authors accept no liability for misuse. Use only on systems you own or are authorized to test. See ETHICS.md.
A purple-team lab for the Model Context Protocol (MCP): build, attack, and defend MCP servers with local + cloud LLMs — with a native desktop GUI.
Tools
No tool list yet. Remote servers get one after the first health check.
FAQ
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
No required environment variable is listed on this record.
PurpleMCP runs locally over stdio.
Last checked 2026-10-28. A purple-team lab for the Model Context Protocol (MCP): build, attack, and defend MCP servers with local + cloud LLMs — with a native desktop GUI.