🐉 Kali Linux MCP Server

📖 Project Overview

The Kali Linux MCP Server is a specialized Model Context Protocol (MCP) implementation designed to connect Large Language Models natively to a comprehensive suite of offensive security, reconnaissance, and enumeration tools. Powered by the FastMCP Python SDK, this server translates natural language requests into safe, encapsulated command-line executions of standard Kali Linux utilities.

By exposing these tools as MCP resources, AI agents can autonomously perform WHOIS lookups, run Nmap scans, fuzz web directories, search exploit databases, and even interface with the Metasploit Framework, all while returning structured standard output and error logs back to the LLM's context window.

Key Features

• 🎯 Comprehensive Offensive Security Toolkit: Natively exposes distinct categories of penetration testing tools to your LLM. The server logically categorizes capabilities, including dedicated modules for Password Cracking & Brute Forcing, as well as Exploitation & Sniffing.
• 📦 Automated & Isolated Containerization: The included Docker configuration ensures a frictionless, reproducible setup. It utilizes the `DEBIAN_FRONTEND=noninteractive` environment variable to suppress manual prompts during Debian package installations, guaranteeing a fully automated build process.
• Native MCP SDK Integration: Built robustly on top of the official `mcp` Python SDK. The environment is flexible, allowing the SDK to be installed globally within the isolated container (`--break-system-packages`) or via a localized Python virtual environment.
• ⚡ Standardized `stdio` Transport: Utilizes direct standard input/output for JSON-RPC communication, bypassing complex network configurations and ensuring out-of-the-box compatibility with AI IDEs (like Cursor and VS Code) and desktop clients (like Claude Desktop).

Demo

Hash Crack

Vulnerability Scan

[![ Autonomous Vulnerability Scanning with GitHub Copilot & Kali MCP Server

](https://raw.githubusercontent.com/cyberillo/kali-mcp-server/refs/heads/main/resources/vulnerability-scan-demo-thumbnail.png)](https://www.youtube.com/watch?v=kSBlrEDb4P0)

Prerequisites

The required dependencies vary entirely based on your chosen execution method.

Option A: 🐳 Docker Execution (Recommended)

By using Docker, the server runs in an isolated container that automatically provisions Python 3, `pip`, and an extensive suite of Kali Linux tools (including `nmap`, `sqlmap`, `tcpdump`, and `metasploit-framework`).

• Docker Engine: Must be installed and running. This method works perfectly on Windows, macOS, and Linux without requiring any local security tools.

Option B: 🐍 Local Python Execution

If you choose to run the script directly on your host machine instead of using Docker, your host must have the tools available natively.

• Operating System: Kali Linux (recommended) or another Linux distribution with the required penetration testing tools installed and in your system's `PATH`.
• Python: Python 3.10 or higher.
• Dependencies: The `mcp` Python SDK (`pip install mcp`).
• Permissions: Some exposed tools, such as `tcpdump` for packet sniffing, explicitly require root privileges to execute natively.

How to Set Up

🐳 Option A: Docker Implementation

Because this server relies on dozens of specific binary tools, packaging it via Docker is the "Gold Standard" approach.

The fastest way to get started is to pull the official image from Docker Hub.

docker pull cyberillo/kali-mcp-server:latest

To run the container interactively using the `stdio` transport required by MCP clients:

docker run -i --rm kali-mcp-server

*(Note: Some tools like `tcpdump` or `netdiscover` require elevated privileges. If you explicitly need these, you may need to append `--privileged` or specific `--cap-add` flags to your `docker run` command, though this is heavily discouraged for general use).*

Alternatively, build the docker image yourself by following the below steps.

• * *

Dockerfile Breakdown

• Base Image: The server is built on top of the official `kalilinux/kali-rolling` base image.

• Toolchain Installation: It updates the system and installs essential tools including `nmap`, `sqlmap`, `metasploit-framework`, `gobuster`, `hydra`, and `john`.

• Wordlists: It automatically extracts the `rockyou.txt` wordlist, as it is zipped by default, making it immediately available for password cracking and fuzzing tools.

• Python Environment: It utilizes the PEP 668 `--break-system-packages` flag to install the `mcp` Python SDK globally within the isolated container.

• * *

1. Clone the repository and navigate to the directory.

git clone https://github.com/cyberillo/kali-mcp-server.git
cd kali-mcp-server

2. 🏗️ Build the image

docker build -t kali-mcp-server .

3. 🏃 Run the container

To run the container interactively using the `stdio` transport required by MCP clients:

docker run -i --rm kali-mcp-server

*(Note: Some tools like `tcpdump` or `netdiscover` require elevated privileges. If you explicitly need these, you may need to append `--privileged` or specific `--cap-add` flags to your `docker run` command, though this is heavily discouraged for general use).*

🛠️ Option B: Local Development Setup

While Docker is the recommended deployment method, you can run the server directly on a Kali Linux machine for development or debugging.

1. Clone the repository and navigate to the directory.

git clone https://github.com/cyberillo/kali-mcp-server.git
cd kali-mcp-server

2. 🐍 Set up a Python Virtual Environment:

python3 -m venv venv
source venv/bin/activate

3. Install the MCP SDK:

pip install mcp

4. Ensure all Kali tools are installed:

Ensure tools like `nmap`, `gobuster`, `sqlmap`, and `msfconsole` are available in your system `PATH`.

5. Run the server in debug mode locally:

You can test the Python script directly using standard input/output.

python3 kali-mcp-server.py

🤖 How to Use

1\. Claude Desktop Configuration

Add the following to your `claude_desktop_config.json` file (usually located at `~/Library/Application Support/Claude/claude_desktop_config.json` on Mac or `%APPDATA%\Claude\claude_desktop_config.json` on Windows).

Go to File > Settings > Developer > Edit Config if you don't find it in the above paths.

Using Docker (Recommended):

{
  "mcpServers": {
    "kali-tools": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "kali-mcp-server"
      ]
    }
  }
}

Using Local Python:

{
  "mcpServers": {
    "kali-tools": {
      "command": "/path/to/your/venv/bin/python3",
      "args": [
        "/path/to/kali-mcp-server.py"
      ]
    }
  }
}

2\. GitHub Copilot (VS Code)

1. If it does not exist, add a directory `.vscode` in your workspace.

2. Add the MCP server by updating `.vscode/mcp.json` as follows.

{
    "servers": {
        "kali-mcp-server": {
            "type": "stdio",
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "kali-mcp-server"
            ]
        }
    },
    "inputs": []
}

3\. Cursor / Other IDEs

For IDEs supporting the Model Context Protocol, configure a new MCP server utilizing the `stdio` transport type.

• Type: `stdio`
• Command: `docker`
• Arguments: `run -i --rm kali-mcp-server`

MCP Tool Definitions

The server exposes 21 specialized tools categorized by their operational phase.

> Pro-Tip for LLMs: When asking the LLM to run `metasploit_exploit`, format options carefully as comma-separated `KEY=VALUE` pairs (e.g., `RHOSTS=192.168.1.5, LHOST=10.0.0.2`).

⚙️ Environment Variables

While the Python server script does not enforce custom application-level environment variables, the Docker environment relies on the following standard Linux variable:

`DEBIAN_FRONTEND`: Set to `noninteractive` in the Dockerfile to prevent the build process from hanging on interactive prompt requests during `apt` installations.

⚠️ Troubleshooting

• Command Timed Out: The server has safety timeouts built into the `run_cmd` function (defaulting to 300 seconds, extended to 600+ for heavier tools like Nikto or Metasploit). If a target is completely unresponsive, the tool will cleanly return a timeout error rather than hanging the LLM indefinitely.
• Permission Denied (Docker): Ensure your user has permissions to run Docker commands, or run the client IDE with appropriate user privileges. Tools like `netdiscover` or `tcpdump` inside the container may silently fail to capture external traffic unless Docker network host routing or privileged modes are enabled.