Skip to main content
Glama
Kali Pentest Lab MCP Server
by MrChr0ma

Kali Pentest Lab MCP Server

An MCP (Model Context Protocol) 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

Related MCP server: Kali Linux Security Tools MCP Server

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.

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.

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.

    git clone https://github.com/MrChr0ma/kali-pentest-mcp-server.git
    cd kali-pentest-mcp-server
  2. Build the image.

    docker build -t kali-pentest-mcp-server .
  3. Test it directly with the MCP Inspector (web UI to list and call tools):

    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:

    mkdir -p ~/.docker/mcp/catalogs && cp kali-pentest.yaml ~/.docker/mcp/catalogs/

    Windows (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):

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

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

    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:

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

    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 coversall 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.Quick nmap scan of 192.168.56.0/24.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.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.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.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, whichsqlmap_scan does not accept yet. Use pages that do not require authentication, or extend the tool.

Local testing

# 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 for the full rules (gateway compatibility constraints and security requirements).

Troubleshooting

  • 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).

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

  • 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>):

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

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

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

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

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

Credits

Built with the help of NetworkChuck's video: https://www.youtube.com/watch?v=GuTcle5edjk.

Tools wrapped: Nmap, Nikto, sqlmap, WPScan, DIRB, Exploit-DB / SearchSploit, on Kali Linux.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      D
      maintenance
      Provides secure access to Kali Linux penetration testing tools including nmap, nikto, dirb, wpscan, and sqlmap for educational vulnerability assessment on whitelisted targets. Runs in a controlled Docker environment and includes reconnaissance capabilities for authorized security testing.
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides Claude Desktop with access to Kali Linux penetration testing tools via a privileged Docker container, enabling network scanning (nmap), web vulnerability scanning (nikto), and custom command execution.
      11
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Wraps common web penetration testing tools in a Docker container and exposes them as Claude tools for educational use in controlled lab environments.
      -