Kali MCP Server

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.

---

Table of Contents

1. Overview
2. Architecture
3. Prerequisites
4. Project Structure
5. Installation
6. Usage
7. Available Tools
8. Extending the Toolset
9. Configuration Reference
10. Legal & Ethical Notice

---

1. Overview

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.

---

2. Architecture

  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.

---

3. Prerequisites

• Docker Engine and Docker Compose v2 (docker compose)
• Python 3.10 or later
• Claude Code

Verify your environment:

docker --version
docker compose version
python3 --version

---

4. Project Structure

File	Description
Dockerfile	Defines the Kali image and installed tools
docker-compose.yml	Builds and runs the container (kali-tools)
server.py	The MCP server; exposes one function per tool
requirements.txt	Python dependencies (mcp)
.mcp.json	Claude Code MCP server configuration
.venv/	Python virtual environment containing dependencies

---

5. Installation

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

Step 2 — Build the Kali container image

docker compose build

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

The container now runs in the background under the name kali-tools.

Step 4 — Verify the setup

docker compose ps

The kali-tools container should be listed with status running.

---

6. Usage

Step 1 — Ensure the container is running

cd /home/hafizfarhad/Documents/kali-mcp
docker compose up -d

Step 2 — Launch Claude Code from the project directory

claude

Claude Code automatically detects the kali server defined in .mcp.json.

Step 3 — Approve the MCP server

Inside Claude Code, run:

/mcp

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

---

7. Available Tools

Network scanning

Tool	Purpose
nmap	Network and port scanning (default options: -sV -T4)
ncat	TCP connect verification (open/closed port checks)
run_nse	Run nmap NSE scripts (mssql, oracle, ipmi, rdp, smtp, …)
nmap_html_report	Convert nmap XML output into an HTML report (xsltproc)

DNS / OSINT

Tool	Purpose
whois	Domain/IP WHOIS registration lookup
dig	DNS record lookups, zone transfers (AXFR), version.bind
subfinder	Passive subdomain enumeration
dnsx	DNS resolution and brute-forcing

Web

Tool	Purpose
httpx	HTTP/HTTPS probing (ProjectDiscovery Go build, httpx-toolkit)
whatweb	Web technology fingerprinting
gau	Fetch known/historical URLs (getallurls)
ffuf	Web fuzzing / content discovery (use FUZZ in the URL; SecLists)
gobuster	Directory, DNS, and virtual-host brute-forcing
nikto	Web server vulnerability scanning
sqlmap	SQL injection detection and exploitation (--batch by default)

Service enumeration

Tool	Purpose
smbclient	List SMB shares (null session by default)
rpcclient	Query MSRPC (users, groups, server info)
smbmap	Enumerate SMB shares and access permissions
enum4linux	All-in-one SMB/Windows enumeration (enum4linux-ng)
showmount	List NFS exports
rsync	List rsync modules / files
onesixtyone	Brute-force SNMP community strings
snmpwalk	Walk an SNMP tree
ssh_audit	Audit SSH algorithms and known weaknesses
mysql	Run a single SQL query (MySQL/MariaDB, non-interactive)
netexec	Authenticated SMB/WinRM/LDAP/MSSQL/… enumeration (nxc)
rpcdump	Dump the MSRPC endpoint mapper (impacket-rpcdump)

Generic helpers

Tool	Purpose
curl	HTTP(S) requests
openssl	Inspect TLS/SSL (certs, protocols; STARTTLS for smtp/imap/…)
jq	Filter/transform JSON
kali_shell	Runs an arbitrary command in the container (for unlisted tools)

---

8. Extending the Toolset

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

1. Add the package to the Dockerfile.
2. Rebuild and restart:

   docker compose build && docker compose up -d
   

To expose a new tool as a dedicated MCP function, duplicate one of the @mcp.tool() wrappers in server.py.

---

9. Configuration Reference

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

---

10. Legal & Ethical Notice

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.