bad-mcp

A small, extensible harness for building test MCP servers that reproduce common MCP attack patterns, so you can measure whether your detector catches them. Built on the official MCP Python SDK (mcp 2.x).

Serves over Streamable HTTP (point a detector at a URL — the realistic "unvetted remote server" case) or stdio, and can also emit an event log offline with no client at all.

Authorized testing only. This is a detection fixture, not a working attack. Run it in an isolated environment dedicated to evaluating your own tooling.

Safety model

Every scenario is deliberately inert:

• Injection / poisoning strings are realistic (so your detector has real signal to match), but the runtime behaviour is harmless: tools return canned text.

• The only side effect a "successful" attack produces is appending a line to a local sink.log — a stand-in for exfiltration that touches nothing sensitive and never leaves the machine.

• All referenced secrets are canaries (~/.bad-mcp/canary_secret, CANARY-TOKEN-...). No real files are read; there is no network egress.

Related MCP server: MEOK MCP Test MCP

Attack scenarios

Install

Requires Python 3.10+ (the mcp SDK's minimum).

python3.10 -m venv venv && . venv/bin/activate
pip install -e .

This installs the repo as the bad_mcp package (see pyproject.toml), which is what makes python -m bad_mcp.cli below work.

Use

List scenarios:

python -m bad_mcp.cli list

Produce an event log offline (no MCP client needed — best for iterating on a static detector):

python -m bad_mcp.cli simulate --out events.jsonl
python detector.py events.jsonl

Run a live remote server over Streamable HTTP and point your detector's "MCP server URL" input at it (this is the realistic setup — an unvetted remote MCP server):

python -m bad_mcp.cli serve-http --port 8971 --out events.jsonl
# detector connects to:  http://127.0.0.1:8971/mcp

The MCP endpoint is mounted at /mcp by default (--path to change). Your detector connects like any MCP client and will observe the rug-pull change mid-session, the poisoned descriptions, and the shadowed/duplicate tools — while the harness records the ground truth to events.jsonl for scoring.

Remote access from another host is off by default (DNS-rebinding protection). To allow it in an isolated test network:

# bind publicly and permit a specific Host header
python -m bad_mcp.cli serve-http --host 0.0.0.0 --port 8971 \
  --allow-host lab-box:8971 --out events.jsonl

# or, for a throwaway isolated net, skip the Host check entirely
python -m bad_mcp.cli serve-http --host 0.0.0.0 \
  --insecure-disable-host-check --out events.jsonl

There is also a local stdio mode for driving with a stdio MCP client:

python -m bad_mcp.cli serve --scenarios rug_pull,tool_shadowing --out events.jsonl

Pick scenarios and the rug-pull trigger:

python -m bad_mcp.cli simulate \
  --scenarios benign_control,rug_pull --trigger after_call --out events.jsonl

Event log (JSONL)

One JSON object per line. Two categories share the stream:

• evidence (ground_truth: false) — what a detector is allowed to see:

  • manifest_snapshot — the tool list served on each list_tools, with per-tool desc_sha / input_schema_sha (diff these across snapshots to catch rug-pulls).

  • tool_call — a tool invocation with its arguments.

  • notification — e.g. tools/list_changed.

• ground truth (ground_truth: true) — labels for scoring: rug_pull_activated, poisoned_tool_present, duplicate_tool_name, shadow_impersonation, exfil_simulated.

detector.py is a baseline detector: it raises findings from evidence only, then scores itself against the ground-truth labels. Replace it with your own tool and reuse the scoring harness.

Note: tool_shadowing and rug_pull interact by design. Two tools sharing a name make a naive "hash changed since last snapshot" heuristic report a spurious rug-pull on that name — a useful reminder to key rug-pull detection on stable tool identity, not name alone.

Extending

Add a subclass of Scenario in scenarios.py and register it in REGISTRY:

class MyScenario(Scenario):
    name = "my_attack"
    def tools(self, state):
        return [types.Tool(name="...", description="...", inputSchema={...})]
    async def on_call(self, name, arguments, ctx, state):
        return [types.TextContent(type="text", text="...")]

Emit a ground-truth label whenever your attack actually fires (see self._label_once(...) and self.events.emit(..., ground_truth=True)) so it shows up in scoring.