Skip to main content
Glama

PepperSpray-MCP

CI License: MIT Python Docker MCP

A Model Context Protocol (MCP) server that puts a penetration-testing toolkit behind an AI assistant. It exposes reconnaissance, scanning, and vulnerability analysis tooling as MCP tools, so a client like Claude can drive a security assessment conversationally while the heavy lifting runs inside a sandboxed Docker container.

⚠️ Authorized use only

This project is for authorized security testing, research, and education. Only run it against systems you own or have explicit written permission to test. Unauthorized scanning or exploitation is illegal in most jurisdictions. You are solely responsible for how you use it. Provided as-is, with no warranty.

Architecture

MCP client (Claude)
      │  stdio
      ▼
mcp-pepperspray-wrapper.sh ──► tcp_stdio_bridge.py ──► TCP
                                                        │
                                                        ▼
                                      pepperspray_server.py  (Docker)
                                      ├─ tool registry & execution
                                      ├─ recon / scanning modules
                                      └─ vulnerability analysis
  • pepperspray_server.py: the core server that registers and executes the tooling

  • pepperspray_mcp.py: MCP protocol handlers and tool definitions

  • tcp_stdio_bridge.py: bridges the MCP client's stdio to the container's TCP socket

  • mcp-pepperspray-wrapper.sh: thin launcher the MCP client invokes

Related MCP server: Hercules MCP

Requirements

  • Docker + Docker Compose

  • socat for the stdio to TCP bridge (brew install socat)

Quick start

git clone <repository> pepperspray-mcp && cd pepperspray-mcp
cp .env.example .env
docker compose up -d --build

Register it with Claude Code:

claude mcp add pepperspray -- bash -c "/absolute/path/to/mcp-pepperspray-wrapper.sh"
claude mcp list        # verify it connected

Or add it to any MCP client config manually:

{
  "mcpServers": {
    "pepperspray": {
      "command": "bash",
      "args": ["-c", "/absolute/path/to/mcp-pepperspray-wrapper.sh"],
      "timeout": 300
    }
  }
}

Configuration

Copy .env.example to .env. Core settings (ports, host, timeouts) work out of the box. Optional third-party API keys (Shodan, Censys, VirusTotal) unlock additional enrichment when provided.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables LLMs to execute common security testing tools like nmap, sqlmap, hydra, and metasploit through a secure Docker container. Provides controlled access to penetration testing utilities with configurable timeouts and tool discovery capabilities.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to perform professional penetration testing through a containerized Kali Linux environment, exposing industry-standard offensive security tools as structured MCP tools.
      45
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to autonomously execute over 200 open-source penetration testing tools via MCP, including reconnaissance, web exploitation, and brute-forcing, through a unified server architecture with Docker sandboxing for safe execution.
      60
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      MCP server for offensive-security tooling, enabling AI agents to run reconnaissance, CVE intelligence, JavaScript analysis, HTTP probing, and port scanning against authorized targets.
      10
      MIT