Enables running Kali Linux penetration-testing tools (e.g., nmap, sqlmap, ffuf) inside a Docker container for network scanning, web testing, and service enumeration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@reconbox-mcp Scan scanme.nmap.org for open ports"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server that enables Claude to run Kali Linux
penetration-testing tools — such as nmap, sqlmap, and ffuf — without
installing them on the host machine. All tools run inside an isolated Kali
Linux Docker container, keeping the host system clean and the tooling
self-contained.
Compatible with any Linux distribution that supports Docker.
Related MCP server: Kali Linux Security Tools MCP Server
This project connects Claude Code to a suite of penetration-testing tools through three components:
Claude Code — the AI assistant running on the host machine.
MCP server (server.py) — a lightweight bridge that receives tool
requests from Claude and executes them inside the container.
Kali container — an isolated environment containing the security tools.
When Claude invokes a tool, the request flows through the MCP server, which
runs the corresponding command inside the container via docker exec and
returns the output.
User → Claude Code → server.py (MCP) → Kali container
(tools execute here)Layer | Location | Responsibility |
Claude Code | Host | Interprets user requests, calls tools |
MCP server | Host | Bridges Claude and the container |
Kali container | Docker (host) | Executes the actual security tools |
This design isolates all tooling within the container. The host machine requires only Docker and Python.
Docker Engine and Docker Compose v2 (docker compose)
Python 3.10 or later
Claude Code
Verify your environment:
docker --version
docker compose version
python3 --versionFile | Description |
| Defines the Kali image and installed tools |
| Builds and runs the container ( |
| The MCP server; exposes one function per tool |
| Python dependencies ( |
| Claude Code MCP server configuration |
| Python virtual environment containing dependencies |
Complete these steps once to set up the project.
Step 1 — Set up the Python environment
cd /home/hafizfarhad/Documents/kali-mcp
python3 -m venv .venv
./.venv/bin/pip install -r requirements.txtStep 2 — Build the Kali container image
docker compose buildThis downloads the Kali base image and installs the security tools. The first build may take several minutes.
Step 3 — Start the container
docker compose up -dThe container now runs in the background under the name kali-tools.
Step 4 — Verify the setup
docker compose psThe kali-tools container should be listed with status running.
Step 1 — Ensure the container is running
cd /home/hafizfarhad/Documents/kali-mcp
docker compose up -dStep 2 — Launch Claude Code from the project directory
claudeClaude Code automatically detects the kali server defined in .mcp.json.
Step 3 — Approve the MCP server
Inside Claude Code, run:
/mcpLocate the kali server and approve it. This is required only on first use.
Step 4 — Issue requests in natural language
Claude selects and runs the appropriate tool automatically. Examples:
"Run an nmap scan against scanme.nmap.org."
"Fingerprint the web technologies used by https://example.com."
"Check http://testsite.local/page?id=1 for SQL injection."
Stopping the container
docker compose stop # pause the container (faster restart later)
docker compose down # stop and remove the containerNetwork scanning
Tool | Purpose |
| Network and port scanning (default options: |
| TCP connect verification (open/closed port checks) |
| Run nmap NSE scripts (mssql, oracle, ipmi, rdp, smtp, …) |
| Convert nmap XML output into an HTML report (xsltproc) |
DNS / OSINT
Tool | Purpose |
| Domain/IP WHOIS registration lookup |
| DNS record lookups, zone transfers (AXFR), |
| Passive subdomain enumeration |
| DNS resolution and brute-forcing |
Web
Tool | Purpose |
| HTTP/HTTPS probing (ProjectDiscovery Go build, |
| Web technology fingerprinting |
| Fetch known/historical URLs ( |
| Web fuzzing / content discovery (use |
| Directory, DNS, and virtual-host brute-forcing |
| Web server vulnerability scanning |
| SQL injection detection and exploitation ( |
Service enumeration
Tool | Purpose |
| List SMB shares (null session by default) |
| Query MSRPC (users, groups, server info) |
| Enumerate SMB shares and access permissions |
| All-in-one SMB/Windows enumeration ( |
| List NFS exports |
| List rsync modules / files |
| Brute-force SNMP community strings |
| Walk an SNMP tree |
| Audit SSH algorithms and known weaknesses |
| Run a single SQL query (MySQL/MariaDB, non-interactive) |
| Authenticated SMB/WinRM/LDAP/MSSQL/… enumeration ( |
| Dump the MSRPC endpoint mapper ( |
Generic helpers
Tool | Purpose |
| HTTP(S) requests |
| Inspect TLS/SSL (certs, protocols; STARTTLS for smtp/imap/…) |
| Filter/transform JSON |
| Runs an arbitrary command in the container (for unlisted tools) |
Temporary (no rebuild required)
Ask Claude to install a package via kali_shell, for example:
apt-get update && apt-get install -y amass. Packages installed this way are
lost when the container is removed (docker compose down).
Permanent
Add the package to the Dockerfile.
Rebuild and restart:
docker compose build && docker compose up -dTo expose a new tool as a dedicated MCP function, duplicate one of the
@mcp.tool() wrappers in server.py.
Command timeout — Long-running commands are terminated after
DEFAULT_TIMEOUT (300 seconds). Adjust this value in server.py.
Network mode — The container uses Docker's default bridge network.
To scan hosts on the local network directly, set network_mode: host in
docker-compose.yml.
Container name — Defined as kali-tools in both docker-compose.yml
and server.py. Keep these values in sync if changed.
These tools must only be used against systems you own or for which you have explicit written authorization (for example, a personal lab, a Capture The Flag exercise, or a sanctioned penetration test). Unauthorized use against third-party systems is illegal. The authors assume no liability for misuse.
This server cannot be deployed
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
AI pentesting: run scans, triage vulnerabilities, review PRs, manage schedules and assets.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
