MCPwner

Beware the Badger

Model Context Protocol server for autonomous security research

Compatible with:

---

Table of Contents

• Overview
• Workflow
• Integrated Tools
• Installation
• Architecture
• Data Persistence
• Security Considerations
• License

Overview

MCPwner is an MCP server that gives your LLM agent a full offensive-security toolkit. It exposes 55+ containerized tools through a single MCP interface - SAST, SCA, secrets, IaC, reconnaissance, DAST, coverage-guided fuzzing, CodeQL (builtin and custom queries), a headless browser, an OOB callback server, a PoC-script sandbox with deterministic oracles, and a persistent findings ledger.

The architecture is designed for agent-driven vulnerability research: a single agent session - model-agnostic (Claude, Cursor, Kiro, Gemini, or any MCP-capable coding agent) - works through the research phases (recon, code audit, PoC validation, adversarial review), recording every step in the shared findings ledger. Each finding progresses from hypothesis through empirical proof to verified report - "no exploit, no report."

Note: This project is under active development. Learn more about MCPs here.

Workflow

MCPwner is the tool server; your LLM agent is the brain. A typical deep-research engagement:

Phase	What happens	MCPwner tools used
Workspace	Clone target, detect stack	create_workspace, detect_languages
Discover	Broad scan for known patterns	run_sast_scan, run_sca_scan, run_secrets_scan, run_reconnaissance_chain, execute_query
Triage	Kill false positives, prove reachability	index_code_facts, query_code_facts, execute_query (custom CodeQL)
Research	Hunt novel bugs via diffs and variant analysis	diff_discovery, run_fuzzing_scan, custom CodeQL
Prove	Empirical validation with deterministic oracles	run_poc_scan (sandbox), run_dast_scan, run_utilities_scan (chromium)
Report	Only oracle-verified findings ship	upsert_finding, generate_report

The ledger uses deep-merge upserts, so a later phase's review verdict never clobbers the earlier poc data (and vice-versa) - and it stays consistent if the agent's context is reset mid-engagement.

Integrated Tools

Reconnaissance

Subfinder	Amass	Nmap	Masscan	ffuf

bbot	httpx	Katana	gau	Arjun

wafw00f	Kiterunner

Static Application Security Testing (SAST)

CodeQL	Psalm	Gosec	Bandit	Semgrep

Brakeman	PMD	NodeJsScan	Joern	YASA	OpenGrep

Source Fuzzing

Atheris	Jazzer	Jazzer.js	PHP-Fuzzer

Secrets Scanning

Gitleaks	TruffleHog	detect-secrets	Whispers	Hawk-Eye

Software Composition Analysis (SCA)

Grype	Syft	OSV-Scanner	Retire.js

Infrastructure & IaC Security

Checkov	KICS	Terrascan	TFSec	Hadolint

Dynamic Application Security Testing (DAST)

sqlmap	NoSQLMap	Commix	Dalfox	SSTImap

SSRFmap	jwt_tool	interactsh

Utilities

Linguist	WireMock	Mitmproxy	aiohttp	Chromium w. Playwright

PoC Validation

PoC-Script Sandbox
Deterministic oracle runner

The PoC sandbox runs agent-authored Python/bash exploit scripts inside the target network and returns a deterministic oracle verdict (pass/fail based on exit code or explicit markers). This is how MCPwner proves logic bugs, IDOR/BOLA, race conditions, and access-control bypasses that off-the-shelf DAST cannot express.

Installation

Prerequisites

System Requirements:

• Docker Engine 20.10+ and Docker Compose 2.0+
• 8GB RAM minimum (16GB recommended for running multiple tools)
• 20GB free disk space (security tool images are large)
• Supported platforms: Linux, macOS, Windows (with WSL2)

MCP Client:

• Claude Desktop, Cursor, Kiro, or any MCP-compatible client

Setup

1. Clone the repository:

   git clone https://github.com/nedlir/mcpwner.git
   cd mcpwner

2. Configure the server:

   cp .env.example .env
   cp config/config.yaml.example config/config.yaml

3. Start the services:

   docker compose up -d --build

4. Verify services are running:

   docker compose ps

Connect Your IDE

Once Docker containers are running, add MCPwner to your MCP client.

Dynamic Tool Registration: MCPwner uses Docker Compose profiles for opt-in tool categories. The .env file's COMPOSE_PROFILES variable controls which containers start. The MCP server probes running containers at startup and registers only healthy tools - if a container is down, its tools simply don't appear. Tools in the utilities category run unconditionally.

One-Click Install (requires Docker running):

Manual Configuration:

Add to your MCP configuration file (claude_desktop_config.json, mcp.json, etc.):

{
  "mcpServers": {
    "mcpwner": {
      "command": "docker",
      "args": ["exec", "-i", "mcpwner-server", "python", "src/server.py"],
      "env": {}
    }
  }
}

Restart your MCP client to load the new server configuration.

Scanning Local Projects

Mount your projects into the container by adding a volume in docker-compose.yaml:

services:
  mcpwner:
    volumes:
      - /path/to/your/projects:/mnt/projects:ro

Then use create_workspace with source_type="local" and source="/mnt/projects/my-project".

Architecture

graph LR
    subgraph IDE[" "]
        LLM[🤖<br/>LLM]
        Client[MCP Client]
        LLM -.-> Client
    end

    Server[MCPwner Server]

    SAST[SAST Tools]
    Secrets[Secrets Scanning]
    SCA[SCA Tools]
    Recon[Reconnaissance]
    CodeQL[CodeQL Service]
    Linguist[Language Detection]
    Utilities[Utilities]
    IaC[IaC Security]
    Fuzzing[Source Fuzzing]
    DAST[DAST Tools]
    PoC[PoC Sandbox]

    Client -->|JSON-RPC 2.0| Server
    Server -->|HTTP| SAST
    Server -->|HTTP| Secrets
    Server -->|HTTP| SCA
    Server -->|HTTP| Recon
    Server -->|HTTP| CodeQL
    Server -->|HTTP| Linguist
    Server -->|HTTP| Utilities
    Server -->|HTTP| IaC
    Server -->|HTTP| Fuzzing
    Server -->|HTTP| DAST
    Server -->|HTTP| PoC

    style LLM fill:#7C3AED,stroke:#5B21B6,stroke-width:3px,color:#fff
    style Client fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#fff
    style Server fill:#F5A623,stroke:#C17D11,stroke-width:3px,color:#fff
    style SAST fill:#E74C3C,stroke:#C0392B,stroke-width:2px,color:#fff
    style Secrets fill:#9B59B6,stroke:#7D3C98,stroke-width:2px,color:#fff
    style SCA fill:#1ABC9C,stroke:#16A085,stroke-width:2px,color:#fff
    style Recon fill:#00BCD4,stroke:#0097A7,stroke-width:2px,color:#fff
    style CodeQL fill:#E67E22,stroke:#CA6F1E,stroke-width:2px,color:#fff
    style Linguist fill:#3498DB,stroke:#2874A6,stroke-width:2px,color:#fff
    style Utilities fill:#6D28D9,stroke:#4C1D95,stroke-width:2px,color:#fff
    style IaC fill:#059669,stroke:#047857,stroke-width:2px,color:#fff
    style Fuzzing fill:#B91C1C,stroke:#7F1D1D,stroke-width:2px,color:#fff
    style DAST fill:#D35400,stroke:#A04000,stroke-width:2px,color:#fff
    style PoC fill:#DC2626,stroke:#991B1B,stroke-width:2px,color:#fff
    style IDE fill:none,stroke:#ddd,stroke-width:2px,stroke-dasharray: 5 5

Loading

Design Principles:

• Container isolation for security tool execution
• Standardized output (SARIF/JSON) for LLM consumption
• Dynamic tool registration - only healthy containers appear as tools
• Persistent findings ledger with deep-merge semantics across research phases
• Deterministic oracles for PoC validation (exit code, markers, OOB callbacks, XSS execution)

Agent Workflow

MCPwner is tool infrastructure. A single agent session - model-agnostic (Claude, Cursor, Kiro, Gemini, or any MCP-capable coding agent) - drives the whole engagement, running each phase itself (recon → API mapping → environment → code audit → vulnerability research → PoC → review) and recording progress in the findings ledger. There is no separate orchestration service or configuration file: MCPwner exposes tools, the agent supplies the workflow.

For a long, isolated sub-task - canonically, standing up and driving a live target environment in a container - the agent may optionally offload to a helper session if its host supports one, but the flow never depends on it.

Data Persistence

MCPwner persists workspace metadata, CodeQL databases, and findings across container restarts using file-based storage in the shared Docker volume (/workspaces/.metadata/). The findings ledger is always available (no container health gate) - it's how the agent tracks findings across phases and recovers state after a context reset.

Workspace Cleanup:

• delete_files=True, delete_metadata=False - Free disk space, preserve history
• delete_files=True, delete_metadata=True - Complete removal
• delete_files=False, delete_metadata=True - Remove from list, keep files

Security Considerations

MCPwner executes security tools that perform intrusive operations. Only use on systems you own or have explicit permission to test. The PoC sandbox runs arbitrary agent-authored code inside a resource-capped, unprivileged container - but it is connected to the target network by design.

Restrict MCP server access to authorized users. Review tool configurations before running scans. Follow responsible disclosure practices. Never commit credentials to configuration files - use environment variables.

License

Apache 2.0