Kali Pentest Lab MCP Server
by MrChr0ma
README.md
# Kali Pentest Lab MCP Server
An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets **Claude Desktop** drive classic Kali Linux web-pentest tools (nmap, nikto, sqlmap, wpscan, dirb, searchsploit) **against an authorized home lab only**.
Everything runs in a Kali Linux Docker container behind the Docker MCP gateway, as a non-root user, with a lab scope enforced in code: every tool refuses any target outside the configured ranges.
> [!WARNING]
> **Educational use only.** This project exists to learn how web attacks work in order to detect and defend against them. Only scan machines you own or are explicitly authorized to test (DVWA, a test WordPress, Metasploitable... on a private or host-only network). Unauthorized scanning is illegal in most countries.
## Table of contents
- [Tools](#tools)
- [How it works](#how-it-works)
- [Security model](#security-model)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage examples](#usage-examples)
- [Local testing](#local-testing)
- [Adding a tool](#adding-a-tool)
- [Troubleshooting](#troubleshooting)
- [Credits](#credits)
- [License](#license)
## Tools
| MCP tool | Wraps | What it does |
|---|---|---|
| `nmap_scan` | nmap | Port/service scan of a lab host or CIDR (max /24). Profiles: `quick` (`-T4 -F`), `service` (`-sV`, default), `scripts` (`-sV -sC`). Optional `ports` (e.g. `22,80,8000-8100`). |
| `nikto_scan` | nikto | Web server misconfiguration and known-issue scan, non-interactive, bounded by `-maxtime`. |
| `sqlmap_scan` | sqlmap | SQL injection detection in `--batch` mode. `level` 1-3, `risk` 1-2, optional POST `data`, `enumerate` = `none` / `dbs` / `tables`. No shells, no file read/write. |
| `wpscan_scan` | wpscan | WordPress scan (version, plugins, themes, users). `enumerate` from `vp`, `ap`, `vt`, `at`, `u` (default `vp,vt,u`). |
| `dirb_scan` | dirb | Non-recursive content discovery with the `common`, `small` or `big` wordlist, optional `extensions` (e.g. `.php,.txt`). |
| `searchsploit_search` | searchsploit | Offline search in the local Exploit-DB copy. No target contacted. |
| `server_info` | - | Tool versions, active scope, timeouts, WPScan token status and nmap raw-socket mode. |
Every result starts with a header line (tool, target, duration, exit code), then the tool output (truncated if very long, beginning and end kept), then a short summary (open ports, findings, injectable parameters...).
## How it works
```
Claude Desktop
└─ Docker MCP gateway (docker mcp gateway run --profile pentest_lab)
└─ kali-pentest container (kalilinux/kali-rolling, user mcpuser, stdio)
└─ nmap / nikto / sqlmap / wpscan / dirb / searchsploit
└─ lab targets (inside ALLOWED_TARGETS only)
```
The gateway starts the container with `docker run --rm -i --init --security-opt no-new-privileges --pull never`, so the image must be built locally first.
| File | Role |
|---|---|
| `Dockerfile` | Kali image, tools, Python venv in `/opt/venv`, non-root user, nmap capability setup, WPScan DB pre-download |
| `requirements.txt` | Python dependencies (`mcp[cli]` 1.x) |
| `kali_pentest_server.py` | The whole server (FastMCP, stdio) |
| `kali-pentest.yaml` | Docker MCP server definition (env, config, optional secret) |
| `CLAUDE.md` | Contributor rules: gateway constraints, security requirements, how to add a tool |
## Security model
- **Scope check first.** URLs must be `http`/`https`; the host is resolved inside the container and **every** resolved IP must be in `ALLOWED_TARGETS` (or the hostname listed literally). nmap only accepts a single host or a CIDR of at most 256 addresses fully inside an allowed network. Refusals start with 🔒 and show the active scope. An empty scope refuses everything.
- **No shell, ever.** Commands run with `asyncio.create_subprocess_exec` and an argument list; stdin is `/dev/null` so a tool can never read the MCP channel.
- **Whitelist, don't blacklist.** Every option comes from a fixed list or a strict regex; raw flags are never accepted. Dangerous options (`--os-shell`, `--sql-shell`, `--file-read`, `--file-write`, searchsploit `-m`/`-x`/`-u`...) are not exposed.
- **Time-bounded.** Each run is limited by `SCAN_TIMEOUT`; on timeout the whole process group gets SIGINT then SIGKILL, and the partial output is returned with ⏱️.
- **Least privilege.** Runs as `mcpuser` (uid 1000). The default nmap has **no** file capability and uses TCP connect scans (`-sT`). A separate `nmap-raw` copy carries `cap_net_raw` only, used when `NMAP_RAW=true` and the container allows it.
- **Secrets.** The optional WPScan API token is only passed to wpscan; it is never logged or displayed.
- **No management tools.** By default the Docker MCP gateway adds its own tools (`mcp-find`, `mcp-add`, `mcp-config-set`, `code-mode`...) next to the server's. `mcp-config-set` could change the scope from the chat, so installation step 6 turns them off.
- **Logs** go to stderr (stdout is the MCP channel).
Known limits: DNS answers may change between the check and the scan, and a tool that follows an HTTP redirect (sqlmap answers "yes" in batch mode) could leave the scope. Keep the lab on an isolated network as a second layer.
<details>
<summary>Why the Dockerfile touches nmap's capabilities</summary>
On Kali, the `nmap` package post-install script sets `cap_net_raw,cap_net_admin,cap_net_bind_service+eip` on `/usr/lib/nmap/nmap` whenever `setcap` is installed. `cap_net_admin` is outside Docker's default capability bounding set, so that binary then refuses to execute ("Operation not permitted"). `/usr/bin/nmap` is also a wrapper script that forces `--privileged` for non-root users.
The Dockerfile therefore strips those capabilities, links `/usr/local/bin/nmap` straight to the real binary, and creates `nmap-raw` with `cap_net_raw` only. The Docker MCP gateway always uses `no-new-privileges`, which disables file capabilities, so raw SYN scans (`NMAP_RAW=true`) only work with a plain `docker run`; under the gateway the server detects it and falls back to `-sT` with a warning.
</details>
## Prerequisites
- Docker Desktop 4.62+ with the **MCP Toolkit** enabled (`docker mcp version` should work).
- Several GB of free disk space (the image is about 1 GB).
- Claude Desktop.
- A lab network reachable from Docker containers (VirtualBox/VMware host-only or NAT network, Hyper-V switch...).
## Installation
1. **Clone the repository.**
```bash
git clone https://github.com/MrChr0ma/kali-pentest-mcp-server.git
cd kali-pentest-mcp-server
```
2. **Build the image.**
```bash
docker build -t kali-pentest-mcp-server .
```
3. **Test it directly** with the MCP Inspector (web UI to list and call tools):
```bash
npx @modelcontextprotocol/inspector docker run -i --rm -e ALLOWED_TARGETS=192.168.56.0/24 kali-pentest-mcp-server
```
4. **Register the server in a dedicated Docker MCP profile.** `docker mcp` only reads `file://` definitions located under `~/.docker/mcp/catalogs`, so copy the YAML there first.
macOS / Linux:
```bash
mkdir -p ~/.docker/mcp/catalogs && cp kali-pentest.yaml ~/.docker/mcp/catalogs/
```
Windows (PowerShell):
```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.docker\mcp\catalogs" | Out-Null
Copy-Item kali-pentest.yaml "$env:USERPROFILE\.docker\mcp\catalogs\"
```
Then create the profile and add the server. `docker mcp` turns the name `pentest-lab` into the profile **ID** `pentest_lab`, which every later command expects (check with `docker mcp profile list`):
```bash
docker mcp profile create --name pentest-lab
docker mcp profile server add pentest_lab --server file://kali-pentest.yaml
```
5. **Set the lab scope** (replace with your lab networks, comma-separated) and a scan timeout below your client's tool-call limit (Claude can give up after about 80 s, so 60 s is a safe value):
```bash
docker mcp profile config pentest_lab --set "kali-pentest.allowed_targets=192.168.56.0/24" --set "kali-pentest.scan_timeout=60"
docker mcp profile config pentest_lab --get-all
```
> [!CAUTION]
> Re-running `docker mcp profile server add` for a server that is already in the profile **resets its configuration**: the scope falls back to the default private ranges. Always set the scope again afterwards and check it with `--get-all` or `server_info`.
6. **(Recommended) Turn off the gateway management tools**, so the client only sees the 7 pentest tools:
```bash
docker mcp feature disable dynamic-tools
```
This setting is global: a gateway started **without** `--profile` (such as the default `MCP_DOCKER` entry) then exposes no tools at all. Undo it with `docker mcp feature enable dynamic-tools`.
7. **(Optional) WPScan API token.** Uncomment the `secrets` block in `kali-pentest.yaml`, copy it to `~/.docker/mcp/catalogs` again, re-run the `server add` command, set the scope again (step 5), then set the token in Docker Desktop (MCP Toolkit → profile `pentest-lab` → Kali Pentest Lab → Configuration).
8. **Connect Claude Desktop.** Merge this entry into the `mcpServers` object of `claude_desktop_config.json` (Settings → Developer → Edit Config), next to any existing servers:
```json
"kali-pentest-lab": {
"command": "docker",
"args": ["mcp", "gateway", "run", "--profile", "pentest_lab"]
}
```
Config location: macOS `~/Library/Application Support/Claude/`, Linux `~/.config/Claude/`, Windows `%APPDATA%\Claude\` (Microsoft Store version: `%LOCALAPPDATA%\Claude-Data\claude_<id>\`). If you have no other MCP servers, `docker mcp client connect claude-desktop --profile pentest_lab` does it for you.
9. **Restart Claude Desktop completely**, then check:
```bash
docker mcp profile server ls --filter profile=pentest_lab
```
and ask Claude: *"Run server_info"*.
## Configuration
| Variable | Default | Purpose |
|---|---|---|
| `ALLOWED_TARGETS` | `10.0.0.0/8,172.16.0.0/12,192.168.0.0/16` | Comma-separated CIDRs, IPs or hostnames the tools may target. Anything else is refused. |
| `SCAN_TIMEOUT` | `300` | Max seconds per tool run. Keep it below the MCP client's tool-call timeout (60 is a good value with Claude Desktop) so a long scan returns its partial output instead of being dropped by the client. |
| `MAX_OUTPUT_CHARS` | `20000` | Longer output is truncated (beginning and end kept, the cut is marked). |
| `NMAP_RAW` | `false` | `true` enables raw SYN scans (`-sS`). Only effective with a plain `docker run` (see above). |
| `WPSCAN_API_TOKEN` | empty | Optional secret for WPScan vulnerability data. Never logged. |
Empty values (the gateway injects `""` for unset config) fall back to the defaults. Through the gateway, set them with `docker mcp profile config pentest_lab --set kali-pentest.<key>=<value>` (`allowed_targets`, `scan_timeout`, `max_output_chars`).
> [!IMPORTANT]
> The default scope covers **all** private ranges, which may include your home, school or office network. Always narrow it to your lab networks.
## Usage examples
Ask Claude in natural language. The IP addresses below are **examples** taken from VirtualBox's default host-only network (`192.168.56.0/24`): replace them with the addresses of your own lab VMs. Any target outside `ALLOWED_TARGETS` is refused with 🔒, so run `server_info` first to see the active scope.
| Tool | Example prompt |
|---|---|
| `server_info` | *Run server_info.* |
| `nmap_scan` | *Scan 192.168.56.101 with nmap, service profile.*<br>*Quick nmap scan of 192.168.56.0/24.*<br>*Run nmap with the scripts profile on 192.168.56.101, ports 21,22,80,3306.* |
| `nikto_scan` | *Run nikto on http://192.168.56.101/.* |
| `sqlmap_scan` | *Test http://192.168.56.101/mutillidae/index.php?page=user-info.php&username=a&password=b with sqlmap, level 2, and list the databases.*<br>*Run sqlmap on http://192.168.56.101/login.php with POST data user=admin&pass=test, enumerate tables.* |
| `wpscan_scan` | *Run wpscan on http://192.168.56.20/wordpress.*<br>*WPScan http://192.168.56.20/wordpress, enumerate all plugins and users (ap,u).* |
| `dirb_scan` | *Run dirb on http://192.168.56.101/dvwa/ with the small wordlist.*<br>*Dirb http://192.168.56.101/ looking for .php,.txt,.bak files.* |
| `searchsploit_search` | *Search exploits for vsftpd 2.3.4.* |
> [!NOTE]
> DVWA pages need a logged-in session cookie, which `sqlmap_scan` does not accept yet. Use pages that do not require authentication, or extend the tool.
## Local testing
```bash
# MCP Inspector
npx @modelcontextprotocol/inspector docker run -i --rm -e ALLOWED_TARGETS=192.168.56.0/24 kali-pentest-mcp-server
# Quick checks without MCP
docker run --rm --entrypoint nmap kali-pentest-mcp-server --version
docker run --rm --entrypoint searchsploit kali-pentest-mcp-server --disable-colour vsftpd
# Call tools through the gateway, like Claude Desktop does
docker mcp tools call --gateway-arg="--profile=pentest_lab" server_info
```
Server logs go to stderr; add `--verbose` to `docker mcp gateway run` to see them.
## Adding a tool
1. Install the binary in the `Dockerfile`.
2. In `kali_pentest_server.py`, add an `async` function decorated with `@mcp.tool()`: all parameters `name: str = ""`, a **single-line** docstring, every option validated against a fixed list or a strict regex, `check_url()` / `check_nmap_target()` called before anything runs, then `execute(...)` (timeout, truncation, header and summary are handled there), all wrapped in `try/except` returning a `❌ Error` string.
3. New configuration goes in `kali-pentest.yaml` (`env` + `config`, never `required`); copy it to `~/.docker/mcp/catalogs` again, re-run `docker mcp profile server add`, then set the scope again (the replace resets the server's config).
4. Rebuild the image, restart Claude Desktop and run `server_info`.
See [CLAUDE.md](CLAUDE.md) for the full rules (gateway compatibility constraints and security requirements).
## Troubleshooting
<details>
<summary><b>Tools do not show up in Claude Desktop</b></summary>
- `docker mcp profile server ls --filter profile=pentest_lab`
- Check the image exists: `docker images kali-pentest-mcp-server` (the gateway uses `--pull never`).
- Check the JSON syntax of `claude_desktop_config.json` (no comments, no trailing commas) and quit Claude Desktop completely before reopening it.
- `profile pentest-lab not found`: use the profile **ID** `pentest_lab` (see `docker mcp profile list`).
- `local file path must resolve within Docker MCP catalogs directory`: copy `kali-pentest.yaml` into `~/.docker/mcp/catalogs` and use `--server file://kali-pentest.yaml`.
- Run the gateway by hand to see errors: `docker mcp gateway run --profile pentest_lab --verbose`
- `calling "initialize": EOF` or no tools at all: run `docker mcp gateway run --profile pentest_lab --dry-run`. A line such as `Missing/invalid config: scan_timeout (... has type "integer", want "string")` means a config value does not match the type declared in `kali-pentest.yaml` (`--set` parses values as JSON: `60` is a number, `"60"` a string).
</details>
<details>
<summary><b>Target refused by scope (🔒)</b></summary>
- Run `server_info` to see the active scope, or `docker mcp profile config pentest_lab --get-all`.
- Set it: `docker mcp profile config pentest_lab --set "kali-pentest.allowed_targets=192.168.56.0/24"` (the whole comma-separated list: the value replaces the previous one), then restart Claude Desktop.
- There is no `.env` or `docker-compose.yml`: if Claude suggests editing one, use the command above instead. The refusal message and `server_info` include this command.
- Make sure the target really exists: the README examples use `192.168.56.x`, which only exists if VirtualBox's host-only adapter is configured (`192.168.56.1`) and a VM is attached to it. Find your VM's address inside the VM (`ip a`) or in your hypervisor (VMware: `C:\ProgramData\VMware\vmnetdhcp.leases`).
- Hostnames must resolve **inside** the container; prefer IP addresses.
</details>
<details>
<summary><b>Docker Desktop shows Claude Desktop as not installed ("Download")</b></summary>
- The MCP Toolkit only looks for `%APPDATA%\Claude\claude_desktop_config.json`. The Microsoft Store version of Claude Desktop keeps its config in `%LOCALAPPDATA%\Claude-Data\claude_<id>\` instead, and the `%APPDATA%\Claude` folder you may see from inside the app is virtualized (it does not exist for other programs).
- The servers still work (check `%LOCALAPPDATA%\Claude\logs\mcp.log` for `Server started and connected successfully`). To make Docker Desktop detect the client, run in an **administrator** PowerShell (adapt the user name and `<id>`):
```powershell
New-Item -ItemType Directory -Force "C:\Users\<you>\AppData\Roaming\Claude" | Out-Null
New-Item -ItemType SymbolicLink -Path "C:\Users\<you>\AppData\Roaming\Claude\claude_desktop_config.json" -Target "C:\Users\<you>\AppData\Local\Claude-Data\claude_<id>\claude_desktop_config.json"
```
</details>
<details>
<summary><b>Extra tools appear (mcp-find, mcp-add, mcp-config-set, code-mode...)</b></summary>
- They come from the gateway's `dynamic-tools` feature, not from this server. Turn them off with `docker mcp feature disable dynamic-tools` (installation step 6) and restart Claude Desktop: `docker mcp tools ls --gateway-arg="--profile=pentest_lab"` should then list exactly 7 tools.
</details>
<details>
<summary><b>Target unreachable from the container</b></summary>
- Docker Desktop containers reach lab VMs through the host's routing (NAT). Test with `docker run --rm alpine ping -c1 192.168.56.101`.
- Check the VM firewall and that the host-only adapter is up. On Linux, some setups need the host network.
</details>
<details>
<summary><b>nmap errors ("Operation not permitted", "requires root privileges")</b></summary>
- Default mode is a TCP connect scan (`-sT`), which needs no privileges.
- `exec: /usr/lib/nmap/nmap: Operation not permitted` means the Kali package capabilities are back on the binary: rebuild from this Dockerfile. `server_info` shows `file capabilities: nmap = none` when it is correct.
- `NMAP_RAW=true` only works without `no-new-privileges`, e.g. `docker run -i --rm -e NMAP_RAW=true -e ALLOWED_TARGETS=192.168.56.0/24 kali-pentest-mcp-server`.
</details>
<details>
<summary><b>Timeouts (⏱️)</b></summary>
- The process is stopped and the partial output is returned.
- Claude gives up on a tool call after about 80 s (for example "the device did not respond in time"), even if the server would allow longer. Keep `scan_timeout` at 60: `docker mcp profile config pentest_lab --set kali-pentest.scan_timeout=60`
- A target that silently drops packets (host firewall, VM powered off) makes every port wait for its timeout: `Not shown: ... filtered tcp ports (no-response)`. A 1000-port service scan then easily exceeds a minute. Start with the quick profile, then run the service profile on the open ports only.
- Prefer a single host, explicit ports, or the small dirb wordlist.
</details>
<details>
<summary><b>WPScan database / vulnerabilities</b></summary>
- The database is downloaded at build time. If `server_info` says it is missing or old, rebuild with `docker build --no-cache -t kali-pentest-mcp-server .`
- Without an API token, WPScan does not list vulnerabilities: get a free token at wpscan.com and follow installation step 7.
</details>
## Credits
Built with the help of NetworkChuck's video: [https://www.youtube.com/watch?v=GuTcle5edjk](https://www.youtube.com/watch?v=GuTcle5edjk).
Tools wrapped: [Nmap](https://nmap.org), [Nikto](https://github.com/sullo/nikto), [sqlmap](https://sqlmap.org), [WPScan](https://wpscan.com), [DIRB](https://dirb.sourceforge.net), [Exploit-DB / SearchSploit](https://www.exploit-db.com/searchsploit), on [Kali Linux](https://www.kali.org).
## License
[MIT](LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues