Kali MCP Server

A production-ready MCP (Model Context Protocol) server running in a Kali Linux Docker container, providing AI assistants with access to 35 security tools covering the full offensive security lifecycle.

Overview

This project provides a Docker containerized MCP server that runs on Kali Linux, giving AI assistants (like Claude) access to a full suite of security and penetration testing tools. The server communicates via Server-Sent Events (SSE) or stdio and allows AI to execute commands in a controlled environment.

Quick Start

Building and Running the Container

# Quick start with the helper script
./run_docker.sh

# Or manually:
docker build -t kali-mcp-server .
docker run -p 8000:8000 kali-mcp-server

Connecting to Claude Desktop

1. Edit your Claude Desktop config file at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kali-mcp-server": {
      "transport": "sse",
      "url": "http://localhost:8000/sse",
      "command": "docker run -p 8000:8000 kali-mcp-server"
    }
  }
}

2. Restart Claude Desktop

3. Test with: /run nmap -F localhost

Available MCP Tools (35)

Core Tools

Reconnaissance & Scanning

Web Application Testing

Credential & Brute-Force Attacks

Payload & Exploit Tools

Encoding & Hash Tools

Share Enumeration

Output Parsing

Evidence & Reporting

Session Management

Tool Details

port_scan - Smart Nmap Wrapper

Runs nmap with predefined scan presets, generating both text and XML output.

/port_scan target=192.168.1.1 scan_type=quick
/port_scan target=10.0.0.0/24 scan_type=aggressive ports=80,443,8080

Scan Presets:

dns_enum - DNS Enumeration

Queries all DNS record types and attempts zone transfers.

/dns_enum domain=example.com
/dns_enum domain=target.com record_types=a,mx,ns,txt

recon_auto - Automated Recon Pipeline

Runs a multi-stage reconnaissance pipeline with configurable depth.

/recon_auto target=example.com depth=quick
/recon_auto target=10.0.0.1 depth=standard
/recon_auto target=target.com depth=deep

Depth Levels:

hydra_attack - Brute-Force Testing

/hydra_attack target=192.168.1.1 service=ssh username=admin passlist=/usr/share/wordlists/rockyou.txt
/hydra_attack target=10.0.0.1 service=ftp userlist=users.txt passlist=passwords.txt threads=32

Supported Services: ssh, ftp, http-get, http-post-form, smb, mysql, rdp, telnet, vnc, pop3, imap, smtp

payload_generate - Msfvenom Payloads

/payload_generate payload_type=reverse_shell platform=linux lhost=10.0.0.1 lport=4444 format=elf
/payload_generate payload_type=meterpreter platform=windows lhost=10.0.0.1 format=exe

Payload Types: reverse_shell, bind_shell, meterpreter Platforms: linux, windows, osx, php, python Formats: elf, exe, raw, python, php, war

reverse_shell - Shell One-Liners

Generates ready-to-use reverse shell commands with listener hints.

/reverse_shell lhost=10.0.0.1 shell_type=bash lport=4444
/reverse_shell lhost=10.0.0.1 shell_type=python lport=9999

Shell Types: bash, python, php, perl, powershell, nc, ruby, java

encode_decode - Encoding Utility

/encode_decode data="hello world" operation=encode format=base64
/encode_decode data="aGVsbG8gd29ybGQ=" operation=decode format=base64
/encode_decode data="<script>alert(1)</script>" operation=encode format=html

Formats: base64, url, hex, html, rot13

hash_identify - Hash Identification

Identifies hash types by regex and returns Hashcat mode numbers and John format names.

/hash_identify hash_value=5d41402abc4b2a76b9719d911017c592
/hash_identify hash_value=$2y$10$abcdefghijklmnopqrstuuABCDEFGHIJKLMNOPQRSTUVWXYZ012345

Supported Types: MD5, SHA-1, SHA-256, SHA-512, bcrypt, SHA-512/256/MD5 Crypt, NTLM, Apache APR1, MySQL, Django

enum_shares - Share Enumeration

/enum_shares target=192.168.1.1 enum_type=all
/enum_shares target=10.0.0.1 enum_type=smb username=admin password=pass

Enum Types: smb (smbclient + enum4linux), nfs (showmount), all

credential_store - Credential Management

Stores discovered credentials as JSON tied to the active session.

/credential_store action=add username=admin password=pass123 service=ssh target=10.0.0.1
/credential_store action=list
/credential_store action=search username=admin

parse_nmap - Nmap Output Parser

Parses both text and XML nmap output into structured JSON with hosts, open ports, services, OS detection, and script output.

/parse_nmap filepath=port_scan_10_0_0_1_quick_20240101_120000.txt
/parse_nmap filepath=scan_results.xml

parse_tool_output - Generic Output Parser

Auto-detects and parses output from nikto, gobuster, dirb, hydra, or sqlmap.

/parse_tool_output filepath=nikto_results.txt
/parse_tool_output filepath=gobuster_output.txt tool_type=gobuster

vulnerability_scan

/vulnerability_scan target=127.0.0.1 scan_type=quick
/vulnerability_scan target=example.com scan_type=comprehensive

Scan Types: quick, comprehensive, web, network

web_enumeration

/web_enumeration target=http://example.com enumeration_type=full

Types: basic, full, aggressive

network_discovery

/network_discovery target=192.168.1.0/24 discovery_type=comprehensive

Types: quick, comprehensive, stealth

Pre-installed Tools

The Docker container includes the following tools, all enabled for use through the run command:

All commands are allowed by default inside the container. The container itself is the security boundary - it runs as a non-root user with no access to the host filesystem.

Security Considerations

• Container isolation: The server runs inside an isolated Docker container as non-root user mcpuser

• Input sanitization: Shell metacharacters (;, &, |) are stripped from all command input

• No host access: The container has no access to the host filesystem or network stack

• Authorization required: Only use for legitimate security testing with proper authorization

• Local only: The container should not be exposed to the internet

Requirements

• Docker

• Claude Desktop or other MCP client (SSE or stdio)

• Port 8000 available on your host machine

Development

Setup

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

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Running Checks

# All checks
./run_tests.sh

# Individual
pyright                          # Type checking
ruff check .                     # Linting
ruff format .                    # Formatting
pytest                           # All tests
pytest tests/test_tools.py       # Single file
pytest -k "session"              # Pattern match

Architecture

Adding a new tool requires changes in three places:

1. kali_mcp_server/tools.py - Implement the async function

2. kali_mcp_server/server.py - Add dispatch in handle_tool_request() and schema in list_available_tools()

3. tests/ - Add tests in both test_tools.py and test_server.py

Acknowledgements

• Kali Linux for their security-focused distribution

• Anthropic for Claude and the MCP protocol

• The open-source security tools community