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

Related MCP server: Kali MCP Server

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)

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

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

DNS / OSINT

Web

Service enumeration

Generic helpers

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.