MCPwner

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

Reconnaissance

Subfinder	Amass	Nmap	Masscan	ffuf

bbot	httpx	Katana	gau	Arjun

wafw00f	Kiterunner

Static Application Security Testing (SAST) Scanning Tools

CodeQL	Psalm	Gosec	Bandit	Semgrep

Brakeman	PMD	NodeJsScan	Joern	YASA

Source Fuzzing

Atheris	Jazzer	Jazzer.js	PHP-Fuzzer

Secrets Scanning Tools

Gitleaks	TruffleHog	detect-secrets	Whispers	Hawk-Eye

Software Composition Analysis (SCA) Tools

Grype	Syft	OSV-Scanner	Retire.js

Infrastructure & IaC Security

Checkov	KICS	Terrascan	TFSec	Hadolint

Utilities

Linguist	WireMock	Mitmproxy	aiohttp	Chromium w. Playwright

Future Tools

The following tools are planned for future releases. Logos will be added as each tool is integrated.

Dynamic Application Security Testing (DAST)

Exploitation and verification tools that run against a live target and produce proof of a vulnerability:

• sqlmap - SQL injection detection and exploitation (data extraction)
• NoSQLMap - NoSQL injection (MongoDB, CouchDB)
• Commix - command injection exploitation
• Dalfox - reflected, stored, and DOM-based XSS
• SSTImap - server-side template injection and code injection (RCE)
• SSRFmap - server-side request forgery exploitation
• jwt_tool - JWT tampering and authentication bypass
• interactsh - OOB interaction server/client for confirming blind vulnerabilities (blind SSRF, blind RCE, blind SQLi, XXE, DNS exfiltration)

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

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 config/config.yaml.example config/config.yaml
   # Edit config/config.yaml as needed
   

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:

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]

    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

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

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

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)