# 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](#1-overview)
2. [Architecture](#2-architecture)
3. [Prerequisites](#3-prerequisites)
4. [Project Structure](#4-project-structure)
5. [Installation](#5-installation)
6. [Usage](#6-usage)
7. [Available Tools](#7-available-tools)
8. [Extending the Toolset](#8-extending-the-toolset)
9. [Configuration Reference](#9-configuration-reference)
10. [Legal & Ethical Notice](#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:

```bash
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**

```bash
cd /home/hafizfarhad/Documents/kali-mcp
python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt
```

**Step 2 — Build the Kali container image**

```bash
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**

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

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

**Step 4 — Verify the setup**

```bash
docker compose ps
```

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

---

## 6. Usage

**Step 1 — Ensure the container is running**

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

**Step 2 — Launch Claude Code from the project directory**

```bash
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**

```bash
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:
   ```bash
   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.