pentesting-mcp-setup

Kali Docker MCP Setup Guide

A comprehensive setup guide for the kali-docker-mcp server - a Model Context Protocol (MCP) server that provides command execution capabilities in a containerized Kali Linux environment for semi-automated penetration testing and security research.

Disclaimer

This tool is provided for educational and authorized security testing purposes only. Use at your own risk. Always ensure you have proper authorization before conducting security assessments.

---

Prerequisites

• Docker & Docker Compose installed and running
• MCP-compatible client (Claude Desktop, Claude Code, Gemini CLI, VS Code with Copilot, etc.)
• Brave API Key (optional) - for web search capabilities (Get one)
• Azure credentials (optional) - for Azure cloud integration
• Basic familiarity with command-line tools

---

Setup Instructions

Step 1: Clone the Repository

cd /path/to/your/projects
git clone https://github.com/hassanaftab93/kali-docker-mcp
cd kali-docker-mcp

Step 2: Configure API Tokens (Optional but Recommended)

Edit config.toml to add your API tokens for enhanced reconnaissance capabilities:

nano config.toml

Available services to configure:

Service	Description	Get Token At
GitHub	Repository and code intelligence mining	https://github.com/settings/tokens
Shodan	Infrastructure and exposed service discovery	https://account.shodan.io/
Censys	Certificate and subdomain discovery	https://censys.io/account/api
VirusTotal	Passive DNS and malware intelligence	https://www.virustotal.com/gui/my-apikey
SecurityTrails	Historical DNS and subdomain data	https://securitytrails.com/app/account/credentials
Hunter.io	Email enumeration and breach data	https://hunter.io/api_keys
DeHashed	Credential breach searches	https://dehashed.com/profile
Wayback Machine	Historical URL and content mining	No API key required

Set enabled = true for services you want to use.

Step 3: Build and Start the Kali Container

docker compose up --build -d

Step 3b: Pull Additional MCP Docker Images (Optional)

If you want to use the Brave Search or Azure MCP servers:

# Brave Search MCP
docker pull mcp/brave-search

# Azure MCP
docker pull mcp/azure

Step 4: Verify the Container is Running

docker ps | grep kali-mcp-server

You should see kali-mcp-server in the output.

Step 5: Configure Your MCP Client

⚠️ IMPORTANT: Disable any built-in terminal or command execution tools in your MCP client to prevent commands from being unintentionally executed on your host system instead of the Kali container.

See the MCP Configuration section below for client-specific setup.

---

MCP Configuration

The mcp-settings.json file contains configurations for multiple MCP servers:

Server	Description	Requirements
kali-mcp-server	Kali Linux pentesting environment	Docker container running
brave	Brave Search API for web searches	BRAVE_API_KEY (Get one)
azure	Azure cloud services integration	Azure credentials configured

Claude Desktop / Claude Code

Add each server individually:

# Kali MCP Server
claude mcp add --transport stdio kali-mcp-server "docker exec -i kali-mcp-server python3 /app/kali_server.py"

# Brave Search (set your API key)
claude mcp add brave "docker run -i --rm -e BRAVE_MCP_TRANSPORT=stdio -e BRAVE_API_KEY=your-api-key mcp/brave-search"

# Azure
claude mcp add azure "docker run -i --rm mcp/azure server start"

Gemini CLI

# Kali MCP Server
gemini mcp add kali-mcp-server "docker exec -i kali-mcp-server python3 /app/kali_server.py"

# Brave Search
gemini mcp add brave "docker run -i --rm -e BRAVE_MCP_TRANSPORT=stdio -e BRAVE_API_KEY=your-api-key mcp/brave-search"

# Azure
gemini mcp add azure "docker run -i --rm mcp/azure server start"

VS Code (Copilot)

Create or edit .vscode/mcp.json in your workspace:

{
  "servers": {
    "kali-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["exec", "-i", "kali-mcp-server", "python3", "/app/kali_server.py"]
    },
    "brave": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "BRAVE_MCP_TRANSPORT", "-e", "BRAVE_API_KEY", "mcp/brave-search"],
      "env": {
        "BRAVE_MCP_TRANSPORT": "stdio",
        "BRAVE_API_KEY": "your-api-key"
      }
    },
    "azure": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/azure", "server", "start"]
    }
  }
}

Other MCP Clients

See mcp-settings.json for the full JSON configuration format.

---

Available Tools

Core MCP Tools

• run_kali_command - Execute commands in Kali environment
• get_job_status - Check background job status
• list_background_jobs - List all running jobs
• cancel_job - Cancel a running job
• get_workspace_info - Get workspace configuration

Interactsh Tools (Out-of-Band Detection)

• start_interactsh - Start out-of-band interaction monitoring
• get_interactsh_status - Check interactsh worker status
• poll_interactsh - Retrieve recorded interactions
• stop_interactsh - Stop interactsh worker

Service Management

• get_service_tokens - Get configured API service tokens

---

Pre-installed Security Tools

Category	Tools
Network Scanning	nmap, masscan
Web Testing	dirb, ffuf, gobuster, nikto, whatweb, wfuzz, nuclei
DNS/Domain	dig, whois, dnsrecon, dnsenum, amass, subfinder
Exploitation	metasploit-framework, sqlmap
Password Attacks	john, hashcat, hydra
SSL/TLS	sslscan, testssl.sh
SMB/Windows	enum4linux, smbclient
Utilities	curl, wget, jq, exiftool, swaks
Wordlists	SecLists

---

Workspace Structure

All pentest artifacts are organized in /app/workspace/{date_target}/:

workspace/
└── {date_target}/
    ├── recon/        # Reconnaissance data
    ├── scans/        # Scan results
    ├── exploits/     # Exploit artifacts
    ├── evidence/     # Evidence collection
    ├── reports/      # Generated reports
    ├── logs/         # Activity logs
    └── screenshots/  # Screenshots

---

Common Commands

Managing the Container

# Start the container
docker compose up -d

# Stop the container
docker compose down

# View container logs
docker logs kali-mcp-server

# Rebuild after changes
docker compose up --build -d

# Enter the container manually
docker exec -it kali-mcp-server /bin/bash

Testing MCP Connection

# Test the MCP server directly
docker exec -i kali-mcp-server python3 /app/kali_server.py

---

Troubleshooting

Container Not Starting

# Check Docker logs
docker logs kali-mcp-server

# Ensure Docker is running
docker info

MCP Client Not Connecting

1. Verify the container is running: docker ps | grep kali-mcp-server
2. Restart your MCP client after configuration changes
3. Check that no other tools are intercepting commands

Permission Issues

The container runs with elevated privileges for security tools. If you encounter permission issues:

# Rebuild the container
docker compose down
docker compose up --build -d

---

Security Notes

• Container runs with necessary privileges (NET_ADMIN, NET_RAW, SYS_ADMIN) for security tools
• All command execution is contained within the Docker environment
• Network mode is set to host for full network access
• API tokens should be configured securely - never commit them to version control
• Resource limits are set to 8GB RAM and 4 CPUs

---

License

This project is an independent open-source contribution and is not affiliated with, endorsed by, or associated with OffSec or Kali Linux. Kali Linux is a trademark of Offensive Security.