MCPwner

Beware the Badger

Model Context Protocol server for security research automation

Compatible with:

Overview

MCPwner is a Model Context Protocol (MCP) server that integrates security testing tools into LLM-driven workflows. It provides a unified interface for secret scanning, static analysis (SAST), software composition analysis (SCA), infrastructure-as-code (IaC) security, source fuzzing, reconnaissance, dynamic application security testing (DAST), and vulnerability research including 0-day discovery.

Instead of manually chaining tools and pasting outputs into your LLM, MCPwner standardizes and streams results directly into the model's working context. This enables continuous reasoning, correlation, and attack path discovery across the security research lifecycle - from mapping attack surfaces and identifying known vulnerabilities to uncovering novel attack vectors.

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

Integrated Tools

Future Tools

The following tools are planned for future releases.

Insecure Deserialization

Gadget-chain and payload generators for weaponizing deserialization sinks identified during SAST. Mature gadget-chain ecosystems exist for Java, .NET, and PHP; Python is covered via malicious-pickle generation (Ruby/Node deserialization is payload-based and lives in the Payloads corpus below):

• ysoserial - Java
• ysoserial.net - .NET
• PHPGGC - PHP
• marshalsec - JVM marshallers/unmarshallers
• Fickling - Python (pickle)

HTTP Request Smuggling

• smuggler - HTTP/1.1 request smuggling / desync (CL.TE, TE.CL, TE.TE)
• h2csmuggler - HTTP/2 cleartext (h2c) upgrade smuggling (distinct from HTTP/2 desync)
• http2smugl - HTTP/2 request smuggling / desync

Payloads

Curated payload and wordlist corpora to back the tools above:

• SecLists - aggregate of fuzzing payloads, credentials, and injection lists
• PayloadsAllTheThings - attack payloads and bypasses organized by vulnerability class
• FuzzDB - fault-injection primitives and predictable resource patterns

Usage Examples

Automated Enumeration Pipeline

"Enumerate and scan example.com"
→ MCPwner chains: Subfinder + Amass → Masscan + Nmap → httpx → Katana + gau → ffuf + Arjun

Scan a GitHub Repository for Secrets

"Scan https://github.com/example/repo for secrets"
→ MCPwner runs Gitleaks, TruffleHog, detect-secrets and correlates findings

Security Audit

"Run a security audit on my Python project"
→ MCPwner runs Bandit (SAST), OSV-Scanner (SCA), and secrets scanning

Attack Path Analysis

"Find vulnerabilities in the authentication module"
→ MCPwner runs CodeQL queries, cross-references with secrets and SCA results

Live Target Exploitation

"Test for SQLi and XSS on http://localhost:8080"
→ MCPwner chains: sqlmap + Dalfox and verifies findings

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:

   root@kitploit:~

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

2. Configure the server:

   root@kitploit:~

   cp config/config.yaml.example config/config.yaml
   # Edit config/config.yaml as needed
   

3. Start the services:

   root@kitploit:~

   docker-compose up -d --build
   

4. Verify services are running:

   root@kitploit:~

   docker-compose ps
   

Connect Your IDE

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

Important: Dynamic Tool Registration MCPwner uses a modular, opt-in architecture. Security tools are governed by Docker Compose profiles.

1. The .env file (COMPOSE_PROFILES=sast,secrets,reconnaissance,dast,etc) dictates which containers are brought online. Alternatively, you can override this and launch specific profiles via the CLI: docker compose --profile sast --profile dast up -d.
2. The MCP server dynamically probes the running containers at startup and registers only the healthy tools with your LLM.
3. If you want to omit specific tools (e.g., semgrep), omit its category (sast) from .env and manually list the other tools you want (bandit,gosec,codeql).
4. Note: Tools in the utilities category (e.g., Linguist, WireMock, Chromium) are treated as permanent core dependencies. They run unconditionally on docker compose up -d to ensure critical cross-tool dependencies (like language detection) always function.

Configuration File Locations:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• Cursor/Kiro: mcp.json in your project or settings directory

One-Click Install (requires Docker running):

Manual Configuration:

Add the following to your MCP configuration file:

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

To scan projects from your host machine, mount them into the container by adding a volume in docker-compose.yaml:

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

Then use the create_workspace tool with:

• source_type="local"
• source="/mnt/projects/my-project"

Data Persistence

MCPwner automatically persists workspace and CodeQL database metadata across container restarts using file-based storage in the shared Docker volume (/workspaces/.metadata/). No configuration required - the system loads existing data on startup and saves after every operation using atomic writes to prevent corruption.

Workspace Cleanup Control:

The cleanup_workspace tool provides granular control:

• delete_files=True, delete_metadata=False - Free disk space but preserve workspace history (recommended)
• delete_files=True, delete_metadata=True - Complete removal of workspace and metadata
• delete_files=False, delete_metadata=True - Remove from list but keep files on disk

Backup:

# Backup entire workspaces volume
docker run --rm -v mcpwner_workspaces:/data -v $(pwd):/backup \
  alpine tar czf /backup/workspaces-backup.tar.gz /data

# Restore volume
docker run --rm -v mcpwner_workspaces:/data -v $(pwd):/backup \
  alpine tar xzf /backup/workspaces-backup.tar.gz -C /

Architecture

MCPwner uses HTTP-based communication between containers to support future remote deployments. While currently optimized for local usage, the architecture can be adapted for remote server deployments with minimal modifications.

Design Principles:

• Container isolation for security tool execution
• Standardized output formats for LLM consumption (SARIF/JSON)
• Extensible plugin architecture for new tools
• Stateless API (memories are managed by user)

Architecture Overview:

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]

    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

    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 IDE fill:none,stroke:#ddd,stroke-width:2px,stroke-dasharray: 5 5

Available MCP Tools

MCPwner exposes the following tools through the MCP interface:

Workspace Management:

• create_workspace - Initialize scanning workspace from local path, Git URL, or GitHub repo
• list_workspaces - List all available workspaces
• cleanup_workspace - Remove workspace and associated data

Findings Ledger:

Workspace-scoped, persisted to disk (<workspace>/findings/<id>.json), and always available — no container or health gate required. This is the source of truth for the multi-agent deep-research pipeline: every hypothesis, PoC result, and review verdict is a finding entry rather than prose.

• upsert_finding - Create or update a finding. Deep-merges into an existing entry by default, so one agent can write its own sub-object (e.g. poc) without clobbering another agent's fields (e.g. review)
• list_findings - List all findings in a workspace, optionally filtered by status (e.g. poc-confirmed, review-approved)
• get_finding - Retrieve a single finding by id

SAST (Static Analysis):

• run_sast_scan - Run static analysis tools (Semgrep, Bandit, Gosec, Brakeman, PMD, Psalm, NodeJsScan, Joern, YASA)
• get_sast_report - Retrieve SAST scan results
• sast_list_tools - List available SAST tools

Secrets Detection:

• run_secrets_scan - Run secrets scanning tools (Gitleaks, TruffleHog, Whispers, detect-secrets, Hawk-Eye)
• get_secrets_report - Retrieve secrets scan results
• secrets_list_tools - List available secrets scanning tools

SCA (Software Composition Analysis):

• run_sca_scan - Analyze dependencies for vulnerabilities (Grype, Syft, OSV-Scanner, Retire.js)
• get_sca_report - Retrieve SCA scan results
• sca_list_tools - List available SCA tools

Reconnaissance:

• run_reconnaissance_scan - Run a single reconnaissance tool (Subfinder, Amass, Nmap, Masscan, httpx, Katana, ffuf, bbot, gau, Arjun, wafw00f, Kiterunner)
• run_reconnaissance_chain - Chain multiple reconnaissance tools sequentially
• get_reconnaissance_report - Retrieve reconnaissance scan results
• reconnaissance_list_tools - List available reconnaissance tools

CodeQL:

• detect_languages - Detect languages in codebase via Linguist
• create_codeql_database - Create CodeQL database for analysis
• list_databases - List available CodeQL databases
• list_query_packs - List available query packs
• execute_query - Run specific CodeQL queries

Infrastructure & IaC Security:

• run_iac_scan - Scan infrastructure-as-code for misconfigurations (Checkov, KICS, Terrascan, TFSec, Hadolint)
• get_iac_report - Retrieve IaC scan results
• iac_list_tools - List available IaC scanning tools

Source Fuzzing:

• run_fuzzing_scan - Run a white-box, coverage-guided fuzzing campaign against a per-target harness (Atheris, Jazzer, Jazzer.js, PHP-Fuzzer)
• get_fuzzing_report - Retrieve fuzzing crash results (crashing input + stack trace)
• fuzzing_list_tools - List available fuzzing engines, filtered by detected language

DAST (Dynamic Application Security Testing):

• run_dast_scan - Run dynamic application security testing tools (sqlmap, NoSQLMap, Commix, Dalfox, SSTImap, SSRFmap, jwt_tool, interactsh)
• get_dast_report - Retrieve DAST scan results
• dast_list_tools - List available DAST tools

Utilities:

• run_utilities_scan - Run a utility tool against a live target (Linguist, WireMock, Mitmproxy, aiohttp, Headless Chromium)
• get_utilities_report - Retrieve utility scan results
• utilities_list_tools - List available utility tools and their config options

Health & Monitoring:

• health_check - Check server and tool availability
• list_tools - List all available tools and their status

Security Considerations

MCPwner executes security tools that may perform intrusive operations. Only use on systems and codebases you own or have explicit permission to test - unauthorized access is illegal. Restrict MCP server access to authorized users and consider network isolation for production deployments. Review tool configurations before running scans as some tools can generate significant network traffic or system load. Log tool execution and results, keeping in mind that security scans can trigger alerts in monitoring systems. Follow responsible disclosure practices when reporting vulnerabilities discovered using MCPwner. Keep Docker images updated and scan containers for vulnerabilities regularly. Never commit API keys, tokens, or credentials to configuration files - use environment variables or secret management systems instead.

Also, you should be responsible for your own security when running these tools and accessing 3rd party libraries, it's suggested to run everything sandboxed and with no special auth (minimized and hardened where feasible)