# MCPwner

> Model Context Protocol server for autonomous vulnerability discovery

- **Type:** MCP server
- **Install:** `agentstack add mcp-nedlir-mcpwner`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nedlir](https://agentstack.voostack.com/s/nedlir)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [nedlir](https://github.com/nedlir)
- **Source:** https://github.com/nedlir/MCPwner

## Install

```sh
agentstack add mcp-nedlir-mcpwner
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

MCPwner
  
  Beware the Badger
  Model Context Protocol server for autonomous security research

[](https://www.docker.com/)
[](https://modelcontextprotocol.io)
[](https://www.python.org/)
[](LICENSE.txt)

**Compatible with:**

[](#installation)
[](#installation)
[](#installation)
[](#installation)
[](#installation)

---

## Table of Contents

- [Overview](#overview)
- [Workflow](#workflow)
- [Integrated Tools](#integrated-tools)
- [Installation](#installation)
- [Documentation](#documentation)
- [Architecture](#architecture)
- [Data Persistence](#data-persistence)
- [License](#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](https://modelcontextprotocol.io).

## 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**](https://github.com/projectdiscovery/subfinder) | [**Amass**](https://github.com/owasp-amass/amass) | [**Nmap**](https://github.com/nmap/nmap) | [**Masscan**](https://github.com/robertdavidgraham/masscan) | [**ffuf**](https://github.com/ffuf/ffuf) |

|                   |                |                 |  |      |
| :------------------------------------------------------: | :----------------------------------------------------: | :------------------------------------------------------: | :----------------------------------------------------------------------------------------------: | :------------------------------------------: |
| [**bbot**](https://github.com/blacklanternsecurity/bbot) | [**httpx**](https://github.com/projectdiscovery/httpx) | [**Katana**](https://github.com/projectdiscovery/katana) |                               [**gau**](https://github.com/lc/gau)                               | [**Arjun**](https://github.com/s0md3v/Arjun) |

|                |              |
| :------------------------------------------------------: | :-------------------------------------------------------: |
| [**wafw00f**](https://github.com/EnableSecurity/wafw00f) | [**Kiterunner**](https://github.com/assetnote/kiterunner) |

## Static Application Security Testing (SAST)

|       |     |        |      |         |
| :--------------------------------------------: | :-----------------------------------------: | :--------------------------------------------: | :-------------------------------------------: | :-----------------------------------------------: |
| [**CodeQL**](https://github.com/github/codeql) | [**Psalm**](https://github.com/vimeo/psalm) | [**Gosec**](https://github.com/securego/gosec) | [**Bandit**](https://github.com/PyCQA/bandit) | [**Semgrep**](https://github.com/semgrep/semgrep) |

|                |  |                |       |              |           |
| :-------------------------------------------------------: | :------------------------------------: | :---------------------------------------------------------: | :-------------------------------------------: | :-------------------------------------------------: | :--------------------------------------------------: |
| [**Brakeman**](https://github.com/presidentbeef/brakeman) | [**PMD**](https://github.com/pmd/pmd)  | [**NodeJsScan**](https://github.com/ajinabraham/NodeJsScan) | [**Joern**](https://github.com/joernio/joern) | [**YASA**](https://github.com/antgroup/YASA-Engine) | [**OpenGrep**](https://github.com/opengrep/opengrep) |

## Source Fuzzing

|        |                        |                            |          |
| :----------------------------------------------: | :-------------------------------------------------------------: | :-------------------------------------------------------------------: | :---------------------------------------------------: |
| [**Atheris**](https://github.com/google/atheris) | [**Jazzer**](https://github.com/CodeIntelligenceTesting/jazzer) | [**Jazzer.js**](https://github.com/CodeIntelligenceTesting/jazzer.js) | [**PHP-Fuzzer**](https://github.com/nikic/php-fuzzer) |

## Secrets Scanning

|              |                    |             |             |            |
| :-----------------------------------------------------: | :-------------------------------------------------------------: | :----------------------------------------------------------: | :----------------------------------------------------: | :----------------------------------------------------: |
| [**Gitleaks**](https://github.com/zricethezav/gitleaks) | [**TruffleHog**](https://github.com/trufflesecurity/trufflehog) | [**detect-secrets**](https://github.com/Yelp/detect-secrets) | [**Whispers**](https://github.com/Skyscanner/whispers) | [**Hawk-Eye**](https://github.com/rohitcoder/hawk-eye) |

## Software Composition Analysis (SCA)

|       |      |            |             |
| :-------------------------------------------: | :-----------------------------------------: | :------------------------------------------------------: | :----------------------------------------------------: |
| [**Grype**](https://github.com/anchore/grype) | [**Syft**](https://github.com/anchore/syft) | [**OSV-Scanner**](https://github.com/google/osv-scanner) | [**Retire.js**](https://github.com/RetireJS/retire.js) |

## Infrastructure & IaC Security

|              |        |           |           |           |
| :----------------------------------------------------: | :-------------------------------------------: | :---------------------------------------------------: | :------------------------------------------------: | :--------------------------------------------------: |
| [**Checkov**](https://github.com/bridgecrewio/checkov) | [**KICS**](https://github.com/checkmarx/kics) | [**Terrascan**](https://github.com/tenable/terrascan) | [**TFSec**](https://github.com/aquasecurity/tfsec) | [**Hadolint**](https://github.com/hadolint/hadolint) |

## Dynamic Application Security Testing (DAST)

|              |          |              |       |           |
| :---------------------------------------------------: | :-------------------------------------------------: | :---------------------------------------------------: | :--------------------------------------------: | :-------------------------------------------------: |
| [**sqlmap**](https://github.com/sqlmapproject/sqlmap) | [**NoSQLMap**](https://github.com/codingo/NoSQLMap) | [**Commix**](https://github.com/commixproject/commix) | [**Dalfox**](https://github.com/hahwul/dalfox) | [**SSTImap**](https://github.com/vladko312/SSTImap) |

|             |           |                     |
| :---------------------------------------------------: | :-------------------------------------------------: | :--------------------------------------------------------------: |
| [**SSRFmap**](https://github.com/swisskyrepo/SSRFmap) | [**jwt_tool**](https://github.com/ticarpi/jwt_tool) | [**interactsh**](https://github.com/projectdiscovery/interactsh) |

## Utilities

|                  |           |             |          |                          |
| :---------------------------------------------------------: | :--------------------------------------------------: | :-----------------------------------------------------: | :------------------------------------------------: | :-------------------------------------------------------------------: |
| [**Linguist**](https://github.com/github-linguist/linguist) | [**WireMock**](https://github.com/wiremock/wiremock) | [**Mitmproxy**](https://github.com/mitmproxy/mitmproxy) | [**aiohttp**](https://github.com/aio-libs/aiohttp) | [**Chromium w. Playwright**](https://github.com/microsoft/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**:

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

2. **Configure the server**:

   ```bash
   cp .env.example .env
   cp config/config.yaml.example config/config.yaml
   ```

3. **Start the services**:

   ```bash
   docker compose up -d --build
   ```

4. **Verify services are running**:
   ```bash
   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. Linguist (language detection / code-facts index) runs unconditionally; the dynamic-testing utilities (Chromium, WireMock, mitmproxy, fuzzer) are opt-in and come up with the `dast` and `poc` profiles.

**One-Click Install (requires Docker running):**

[](https://kiro.dev/launch/mcp/add?name=mcpwner&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22exec%22%2C%22-i%22%2C%22mcpwner-server%22%2C%22python%22%2C%22src%2Fserver.py%22%5D%7D)
[](https://cursor.com/en/install-mcp?name=mcpwner&config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJleGVjIiwiLWkiLCJtY3B3bmVyLXNlcnZlciIsInB5dGhvbiIsInNyYy9zZXJ2ZXIucHkiXX0%3D)
[](https://claude.ai/install-mcp?name=mcpwner&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22exec%22%2C%22-i%22%2C%22mcpwner-server%22%2C%22python%22%2C%22src%2Fserver.py%22%5D%7D)
[](https://vscode.dev/redirect/mcp/install?name=mcpwner&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22exec%22%2C%22-i%22%2C%22mcpwner-server%22%2C%22python%22%2C%22src%2Fserver.py%22%5D%7D)
[](https://windsurf.ai/install-mcp?name=mcpwner&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22exec%22%2C%22-i%22%2C%22mcpwner-server%22%2C%22python%22%2C%22src%2Fserver.py%22%5D%7D)

**Manual Configuration:**

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

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

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

## Documentation

Additional guides live in the [project wiki](https://github.com/nedlir/MCPwner/wiki):

- [Quickstart](https://github.com/nedlir/MCPwner/wiki/Quickstart) - start the tool fleet with `COMPOSE_PROFILES` and wire the MCP server into your client.
- [Configuration](https://github.com/nedlir/MCPwner/wiki/Configuration) - `.env` / `COMPOSE_PROFILES`, `config.yaml`, and the tool port map.
- [Troubleshooting](https://github.com/nedlir/MCPwner/wiki/Troubleshooting) - missing tools, unhealthy containers, and image-build failures.
- [Adding a tool](https://github.com/nedlir/MCPwner/wiki/Adding-a-Tool) - wire a new scanner container into the fleet and the tool registry.

Contributing? See [CONTRIBUTING.md](CONTRIBUTING.md) for code style, pre-commit hooks, and tests.

## Architecture

```mermaid
graph LR
    subgraph IDE[" "]
        LLM[🤖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:#

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nedlir](https://github.com/nedlir)
- **Source:** [nedlir/MCPwner](https://github.com/nedlir/MCPwner)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-nedlir-mcpwner
- Seller: https://agentstack.voostack.com/s/nedlir
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.