Metadata-Version: 2.4
Name: shieldpi-mcp
Version: 0.2.0
Summary: 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).
Project-URL: Homepage, https://shieldpi.io
Project-URL: Documentation, https://github.com/ShieldPi1/shieldpi-watchtower/tree/main/mcp-server
Project-URL: Repository, https://github.com/ShieldPi1/shieldpi-watchtower
Project-URL: Issues, https://github.com/ShieldPi1/shieldpi-watchtower/issues
Project-URL: Leaderboard, https://shieldpi.info
Project-URL: Methodology, https://shieldpi.io/methodology
Author-email: ShieldPi <support@shieldpi.io>
License: MIT
License-File: LICENSE
Keywords: ai-security,anthropic,claude,jailbreak,llm-security,mcp,owasp,prompt-injection,red-team
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# shieldpi-mcp

> **MCP server for [ShieldPi Watchtower](https://shieldpi.io)** — query 27,000+ LLM attack techniques, run scans, and pull breach forensics from any MCP-compatible client (Claude Desktop, Claude Code, Cursor, Continue).

[![PyPI](https://img.shields.io/pypi/v/shieldpi-mcp.svg)](https://pypi.org/project/shieldpi-mcp/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Leaderboard](https://img.shields.io/badge/leaderboard-shieldpi.info-22c55e)](https://shieldpi.info)

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](https://shieldpi.io/dashboard/api-keys).

## Install

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

```bash
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):**

```bash
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`:**

```bash
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):

```json
{
  "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

```bash
claude mcp add shieldpi -- shieldpi-mcp
```

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

```bash
export SHIELDPI_API_KEY="shpi_live_..."
```

### Cursor

Add to `~/.cursor/mcp.json`:

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

### Continue (VS Code / JetBrains)

In `~/.continue/config.json`:

```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

```bash
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](LICENSE).

## Links

- **Product:** [shieldpi.io](https://shieldpi.io)
- **Leaderboard:** [shieldpi.info](https://shieldpi.info)
- **Methodology:** [shieldpi.io/methodology](https://shieldpi.io/methodology)
- **Research:** [shieldpi.io/research](https://shieldpi.io/research)
- **Issues:** [github.com/ShieldPi1/shieldpi-watchtower/issues](https://github.com/ShieldPi1/shieldpi-watchtower/issues)
