shieldpi-mcp 0.2.0

MCP server for ShieldPi Watchtower — query 27,000+ LLM attack techniques, run scans, fetch breach forensics from any MCP-compatible client (Claude Desktop, Claude Code, Cursor).

shieldpi-mcp

MCP server for ShieldPi Watchtower — query 27,000+ LLM attack techniques, run scans, and pull breach forensics from any MCP-compatible client (Claude Desktop, Claude Code, Cursor, Continue).

ShieldPi is the security forensics platform for LLMs and agents. It runs 27,024+ attack techniques across 4 scan modes (Browser / API / Agent / Model), classifies findings on the ExploitDepth L1–L4 scale, and produces a forensic kill-chain narrative + extracted breach evidence (credentials, PII, code, tools, blast radius) for every successful attack.

This MCP server lets you talk to ShieldPi from inside any LLM session.

What you get

Tier	Tool	API key?	Use it for
1	get_methodology	no	Pull the V7 scoring + dedup + judge methodology
1	get_attack_graph	no	Cross-customer success-rate graph by technique × model family
1	get_model_families	no	ShieldPi's family taxonomy + similarity edges
1	get_leaderboard_feed	no	Live data behind shieldpi.info
1	get_leaderboard	no	Top models by best security score
1	get_model_registry	no	All 38+ models ShieldPi can test
2	list_attack_categories	yes	The 15 categories + OWASP mappings
2	list_attack_techniques	yes	Browse the 27k catalog with filters
2	start_scan	yes	Kick off a scan against a target
2	get_scan_intelligence	yes	Pull the breach-forensics package for a scan

Tier-1 works the moment you install. Tier-2 needs a free ShieldPi API key — get one at shieldpi.io/dashboard/api-keys.

Install

Recommended (works on every OS, puts shieldpi-mcp on your $PATH):

pipx install shieldpi-mcp

Don't have pipx? brew install pipx && pipx ensurepath (macOS) or python3 -m pip install --user pipx && pipx ensurepath (Linux/Windows).

Why pipx: Claude Desktop / Cursor / Continue look up shieldpi-mcp on $PATH. pipx handles that automatically. Plain pip install may put the entry point somewhere your MCP client can't find.

Alternative — pip with an explicit modern Python (Python 3.10+ is required):

python3.11 -m pip install --user shieldpi-mcp
# then add ~/Library/Python/3.11/bin (macOS) or ~/.local/bin (Linux) to your PATH

If you see ERROR: Could not find a version that satisfies the requirement shieldpi-mcp, your default pip is using a Python older than 3.10 (common on macOS, where the system python3 is 3.9). Use pipx or pick a modern Python explicitly as above.

Or with uv:

uv tool install shieldpi-mcp

The package ships a shieldpi-mcp console entry point that runs the server over stdio — that's what every MCP client expects.

Configure your client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "shieldpi": {
      "command": "shieldpi-mcp",
      "env": {
        "SHIELDPI_API_KEY": "shpi_live_..."
      }
    }
  }
}

Restart Claude Desktop. Look for the 🔌 plug icon — shieldpi should be listed with 10 tools.

Claude Code

claude mcp add shieldpi -- shieldpi-mcp

Then set the env var in the same shell or in your .envrc:

export SHIELDPI_API_KEY="shpi_live_..."

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "shieldpi": {
      "command": "shieldpi-mcp",
      "env": { "SHIELDPI_API_KEY": "shpi_live_..." }
    }
  }
}

Continue (VS Code / JetBrains)

In ~/.continue/config.json:

{
  "mcpServers": {
    "shieldpi": {
      "command": "shieldpi-mcp",
      "env": { "SHIELDPI_API_KEY": "shpi_live_..." }
    }
  }
}

Try it

Once installed and configured, ask your LLM:

"Using the shieldpi tools, what's the current security ranking of Claude Sonnet 4.5 vs GPT-4o?"

"Pull the ShieldPi methodology and explain ExploitDepth scoring in plain English."

"Browse the prompt_injection category in the ShieldPi attack catalog and pick 3 techniques worth testing on my agent."

"Start a model-mode scan against anthropic/claude-sonnet-4.5 and report when it's done."

Environment variables

Variable	Default	Purpose
SHIELDPI_API_KEY	(none)	Required for tier-2 tools (techniques catalog, scans). Free tier works.
SHIELDPI_API_BASE	https://api.shieldpi.io	Override for self-hosted ShieldPi or staging.
SHIELDPI_TIMEOUT	30	Per-request timeout in seconds.

Develop

git clone https://github.com/ShieldPi1/shieldpi-watchtower.git
cd shieldpi-watchtower/mcp-server
pip install -e ".[dev]"
pytest

The test suite hits live api.shieldpi.io for tier-1 endpoints and skips tier-2 unless SHIELDPI_API_KEY is set.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│            Claude Desktop / Claude Code / Cursor                 │
│                  (MCP Client over stdio)                         │
└──────────────────────────────┬──────────────────────────────────┘
                               │ MCP (JSON-RPC over stdio)
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    shieldpi-mcp (Python)                         │
│  ┌──────────────┐  ┌─────────────────┐                          │
│  │  10 MCP      │  │ ShieldPiClient  │                          │
│  │  tools       │  │   (httpx)       │                          │
│  └──────┬───────┘  └────────┬────────┘                          │
└─────────┼───────────────────┼────────────────────────────────────┘
          │                   │ HTTPS outbound only
          │                   ▼
          │       ┌─────────────────────────────┐
          │       │  https://api.shieldpi.io   │
          │       │  (FastAPI on Hetzner)       │
          │       └─────────────────────────────┘
          ▼
   stdout (MCP responses)

Outbound HTTPS only. No inbound ports. API keys are read from env vars, never logged. The server is single-process, stateless across requests — safe to drop into any client.

License

MIT. See LICENSE.

Links

• Product: shieldpi.io
• Leaderboard: shieldpi.info
• Methodology: shieldpi.io/methodology
• Research: shieldpi.io/research
• Issues: github.com/ShieldPi1/shieldpi-watchtower/issues