Content
# KALI-MCP: AI-Powered Pentesting Bridge
A "Vibecoder" style MCP server that bridges LLMs directly into a Kali Linux environment via Docker. Designed for high-speed, AI-driven security auditing, R&D, and rapid penetration testing simulations.
---
## Features
- **Full Potential:** No command whitelisting — execute any Kali tool (Nmap, SQLMap, Metasploit, etc.) directly via AI.
- **Network-Ready:** Docker capabilities `NET_ADMIN` and `NET_RAW` for stealth scanning and packet crafting.
- **Dockerized:** One-command setup for fully isolated environments.
- **Claude Desktop Integration:** Plug directly into Claude Desktop via MCP config.
- **GPL v3 Licensed:** Free and Open Source.
---
## Prerequisites
Before you begin, make sure you have the following installed:
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) (Windows/macOS/Linux)
- [Claude Desktop](https://claude.ai/download)
- Git
---
## Project Structure
```
kali-mcp/
├── Dockerfile # Kali Linux Docker environment
├── mcp_server.py # MCP bridge server
└── README.md
```
---
## Setup & Installation
### Step 1 — Clone the Repository
```bash
git clone https://github.com/edutechenterprises2023-ops/kali-mcp.git
cd kali-mcp
```
### Step 2 — Build the Docker Image
```bash
docker build -t my-kali-mcp .
```
> This pulls the latest Kali Linux rolling image and installs Nmap, SQLMap, Metasploit, and the MCP Python package.
### Step 3 — Test the Container (Optional)
```bash
docker run -i --rm --cap-add=NET_ADMIN --cap-add=NET_RAW my-kali-mcp
```
If it starts without errors, you're good to go.
---
## Enabling MCP in Docker Desktop
> Docker Desktop has a built-in MCP Toolkit that must be enabled for Claude to communicate with local containers.
1. Open **Docker Desktop**.
2. Click the **Settings** gear icon (top right).
3. Navigate to **Features in Development** (or **Beta Features** depending on your version).
4. Enable **"MCP Toolkit"** / **"Model Context Protocol support"**.
5. Click **Apply & Restart**.
> If you don't see the MCP option, make sure Docker Desktop is updated to the latest version.
---
## Connecting to Claude Desktop
### Step 1 — Locate the Config File
On **Windows**, the Claude Desktop config is located at:
```
C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json
```
> **Tip:** Press `Win + R`, type `%APPDATA%\Claude`, and hit Enter to open the folder directly.
On **macOS**, it's at:
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
---
### Step 2 — Edit the Config File
Open `claude_desktop_config.json` in any text editor (Notepad, VS Code, etc.) and paste in the following:
```json
{
"mcpServers": {
"kali-local": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--cap-add=NET_ADMIN",
"--cap-add=NET_RAW",
"my-kali-mcp"
]
}
}
}
```
---
### Step 3 — Restart Claude Desktop
Fully quit and relaunch Claude Desktop. On Windows:
1. Right-click the Claude icon in the **system tray** (bottom-right corner).
2. Click **Quit**.
3. Reopen Claude Desktop from the Start menu.
---
### Step 4 — Verify the Connection
Once Claude Desktop restarts:
1. Start a new chat.
2. Look for the **🔧 Tools** icon or the MCP indicator in the input bar.
3. You should see **`kali-local`** listed as an available MCP server.
4. Try a test prompt:
```
Run nmap -sV localhost using the kali-local tool
```
If Claude executes the command and returns output, everything is working correctly.
---
## How It Works
The MCP server (`mcp_server.py`) exposes a single tool — `execute_kali_cmd` — that Claude calls to run shell commands inside the Kali container:
```python
import subprocess
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("kali-tools-mcp")
@mcp.tool()
def execute_kali_cmd(command: str) -> str:
"""
Run any Kali Linux terminal command (nmap, sqlmap, etc.)
:param command: The full terminal command to execute.
"""
try:
result = subprocess.check_output(command, shell=True, stderr=subprocess.STDOUT, text=True)
return result
except subprocess.CalledProcessError as e:
return f"Error: {e.output}"
if __name__ == "__main__":
mcp.run()
```
**Flow:** Claude sends a command string → MCP server executes it inside the container → returns output to Claude.
---
## Troubleshooting
| Issue | Fix |
|---|---|
| `docker: command not found` | Ensure Docker Desktop is installed and running |
| Claude doesn't show `kali-local` tool | Check the JSON config for syntax errors and restart Claude Desktop |
| Container exits immediately | Run `docker run -it my-kali-mcp bash` to debug interactively |
| MCP not available in Docker Desktop | Update Docker Desktop to the latest version and enable MCP in Settings |
---
## Security Disclaimer
> ⚠️ **For R&D and educational use only.**
This tool intentionally allows **Remote Code Execution (RCE)** inside the container. Always run in an **isolated lab or VM environment**. Never use against systems you do not own or have explicit written permission to test. The author is not responsible for misuse.
---
## License
[GPL v3](https://www.gnu.org/licenses/gpl-3.0.en.html) — Free and Open Source.
