Skip to content

INSTALLATION_GUIDE.md

Latest commit

 

History

History
524 lines (373 loc) · 10.5 KB

INSTALLATION_GUIDE.md

File metadata and controls

524 lines (373 loc) · 10.5 KB

Kali MCP Server - Complete Installation Guide

This guide covers everything you need to know about installing, using, and managing the Kali Linux MCP Server for Docker Desktop.

Table of Contents

  1. Prerequisites
  2. Installation
  3. Verification
  4. Usage
  5. Management
  6. Troubleshooting
  7. Uninstallation

Prerequisites

Required

  • Docker Desktop (latest version with MCP Toolkit support)
  • 20GB free disk space for Kali tools
  • Stable internet connection for downloading packages

Verify Requirements

# Check Docker is running
docker info

# Check Docker MCP CLI is available
docker mcp version

# Check available disk space
df -h

Installation

Method 1: Automated Setup (Recommended)

The automated setup script handles everything:

cd /home/simbaclaws/kali-mcp-docker-desktop
./setup.sh

What the script does:

  1. ✅ Verifies Docker and Docker Compose are available
  2. ✅ Checks for Docker MCP CLI
  3. ✅ Builds the Kali MCP server container
  4. ✅ Starts the Kali Linux container
  5. ✅ Creates a custom catalog named "my-security-tools"
  6. ✅ Adds the Kali server to the catalog
  7. ✅ Enables the server in Docker Desktop
  8. ✅ Verifies the installation

Expected output:

🐉 Kali Linux MCP Server for Docker Desktop
===========================================

✅ Docker is running
✅ Docker Compose is available
✅ Docker MCP CLI is available

📦 Building MCP server container...
🚀 Starting services...
✅ Services started successfully!

🔧 Adding to Docker Desktop MCP Toolkit...
📚 Creating custom catalog...
✅ Custom catalog created
➕ Adding Kali server to catalog...
✅ Kali server added to catalog
🔌 Enabling Kali server...
✅ Kali server enabled

🔍 Verifying installation...
✅ Kali Linux Security Tools is now available in Docker Desktop!

🎉 Installation Complete!

Method 2: Manual Setup

If you prefer manual control:

cd /home/simbaclaws/kali-mcp-docker-desktop

# 1. Build containers
docker-compose build

# 2. Start services
docker-compose up -d

# 3. Create custom catalog
docker mcp catalog create my-security-tools

# 4. Add Kali server to catalog
docker mcp catalog add my-security-tools kali-linux-tools ./kali-catalog.yaml

# 5. Enable server
docker mcp server enable kali-linux-tools

# 6. Verify
docker mcp server ls

Verification

Command Line Verification

# List enabled MCP servers
docker mcp server ls

# Should show:
# kali-linux-tools    enabled

# View catalog contents
docker mcp catalog show my-security-tools

# Check container status
docker ps | grep kali

# Should show two containers running:
# kali-mcp-server
# kali-tools-container

Docker Desktop Verification

  1. Open Docker Desktop
  2. Click MCP Toolkit in the left sidebar
  3. Look for Kali Linux Security Tools
  4. Status should show as Enabled

Tool Installation Progress

The first time you use the server, it installs kali-linux-everything (~15GB, 1-2 hours).

Monitor progress:

# Watch installation logs
docker-compose logs -f kali-mcp-server

# Or connect to Kali container
docker exec -it kali-tools-container bash
apt list --installed | grep kali-linux-everything

You'll see output like:

Checking if Kali tools are installed...
Installing Kali tools (this may take 1-2 hours on first run)...
Installing: kali-linux-everything package (~15GB)...

Usage

With Ask Gordon (Docker Desktop)

  1. Open Docker Desktop
  2. Click Ask Gordon in the sidebar
  3. Try these prompts:
"List all available Kali tools using kali_list_tools"
"Use kali_help to show me how to use nmap"
"Use kali_nmap with args '-sV localhost' to scan local ports"

With Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kali": {
      "command": "docker",
      "args": ["mcp", "gateway", "run"]
    }
  }
}

Then restart Claude Desktop and try:

"Use kali_nmap to scan 192.168.1.1 with args '-sV -p 1-1000'"

With VS Code (Copilot)

# In your project directory
cd /path/to/your/project
docker mcp client connect vscode

This creates .vscode/mcp.json. Then in VS Code Chat:

"Use kali_help to show me nmap options"

Available Tools

The server provides these MCP tools:

  • kali_exec - Execute any command in Kali Linux
  • kali_list_tools - List all available tools (with optional filter)
  • kali_help - Get help/man page for any tool
  • kali_install - Install additional Kali packages
  • kali_nmap - Network scanning
  • kali_[toolname] - Direct access to 150+ security tools

Example Commands

# List network tools
"Use kali_list_tools with filter 'nmap'"

# Get help for a tool
"Use kali_help with tool 'metasploit'"

# Scan a network
"Use kali_nmap with args '-sV -p 80,443,8080 192.168.1.0/24'"

# Execute custom command
"Use kali_exec with command 'ls -la /usr/bin | grep -i crack'"

# Install additional tools
"Use kali_install with packages 'bloodhound crackmapexec'"

Management

View Status

# List all MCP servers
docker mcp server ls

# View catalog
docker mcp catalog show my-security-tools

# List all catalogs
docker mcp catalog ls

# Container status
docker-compose ps

View Logs

# All logs
docker-compose logs -f

# MCP server only
docker-compose logs -f kali-mcp-server

# Kali container only
docker-compose logs -f kali-linux

# Docker Desktop logs
cat ~/.docker/desktop/log.txt

Restart Services

# Restart all services
docker-compose restart

# Restart specific service
docker-compose restart kali-mcp-server

# Stop all services
docker-compose down

# Start all services
docker-compose up -d

Disable/Enable Server

# Disable server
docker mcp server disable kali-linux-tools

# Enable server
docker mcp server enable kali-linux-tools

# Reset (disable all servers)
docker mcp server reset

Update Server

If you make changes to the MCP server code:

# Rebuild
docker-compose build --no-cache

# Restart
docker-compose up -d

# Update catalog
docker mcp catalog add my-security-tools kali-linux-tools ./kali-catalog.yaml --force

Install Additional Tools

# Connect to Kali container
docker exec -it kali-tools-container bash

# Install packages
apt-get update
apt-get install -y package-name

# Or use the MCP tool
# "Use kali_install with packages 'bloodhound crackmapexec'"

Troubleshooting

Server Not Showing in Docker Desktop

Problem: Kali server doesn't appear in MCP Toolkit

Solutions:

# Verify catalog
docker mcp catalog show my-security-tools

# Re-add to catalog
docker mcp catalog add my-security-tools kali-linux-tools ./kali-catalog.yaml --force

# Re-enable server
docker mcp server enable kali-linux-tools

# Restart Docker Desktop

Containers Not Starting

Problem: docker-compose up fails

Solutions:

# Check Docker is running
docker info

# Check logs
docker-compose logs

# Remove and recreate
docker-compose down -v
docker-compose up -d

# Check for port conflicts
docker ps -a

Image Not Found

Problem: Error: image kali-mcp-server:latest not found

Solutions:

# Build the image
docker-compose build

# Verify image exists
docker images | grep kali-mcp-server

# Force rebuild
docker-compose build --no-cache

Network Errors

Problem: network kali-mcp-docker-desktop_kali-network not found

Solutions:

# Ensure containers are running
docker-compose up -d

# List networks
docker network ls | grep kali

# Recreate network
docker-compose down
docker-compose up -d

Tools Not Installing

Problem: Kali tools don't install on first run

Solutions:

# Check logs for errors
docker logs kali-tools-container -f

# Connect and install manually
docker exec -it kali-tools-container bash
apt-get update
apt-get install -y kali-linux-everything

# Check disk space
df -h

Permission Errors

Problem: Docker socket permission denied

Solutions:

# Linux: Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Verify permissions
ls -l /var/run/docker.sock

# Test Docker access
docker ps

MCP Command Not Found

Problem: docker mcp: command not found

Solution: Update Docker Desktop to a version with MCP Toolkit support (v4.27.0+)

Uninstallation

Automated Uninstallation (Recommended)

cd /home/simbaclaws/kali-mcp-docker-desktop
./uninstall.sh

This removes:

  • ✅ Kali server from Docker Desktop
  • ✅ Custom catalog
  • ✅ Running containers
  • ✅ Docker images
  • ✅ Build artifacts
  • ✅ (Optional) Project files

Manual Uninstallation

# Disable server
docker mcp server disable kali-linux-tools

# Remove from catalog
docker mcp catalog rm my-security-tools

# Stop containers
docker-compose down -v

# Remove images
docker rmi kali-mcp-server:latest
docker rmi kalilinux/kali-rolling:latest

# Remove build artifacts
rm -rf build/ node_modules/

Additional Resources

Security Reminders

⚠️ CRITICAL: Only use these tools:

  • On systems you own
  • With explicit written permission
  • In isolated test environments
  • For legal security testing purposes

This tool provides access to powerful security testing capabilities. Misuse can result in:

  • Legal consequences
  • Network damage
  • Data loss
  • System compromise

Always follow responsible disclosure practices and obtain proper authorization.

Support

If you encounter issues:

  1. Check logs: docker-compose logs -f
  2. Review troubleshooting section above
  3. Verify Docker Desktop version supports MCP Toolkit
  4. Check GitHub issues or create a new one
  5. Ensure you have sufficient disk space and permissions

Next Steps

After installation:

  1. ✅ Verify installation with docker mcp server ls
  2. ✅ Test with Ask Gordon or Claude Desktop
  3. ✅ Wait for tool installation to complete (1-2 hours)
  4. ✅ Explore the 600+ available security tools
  5. ✅ Read Kali documentation for tool usage
  6. ✅ Practice in a safe, isolated environment

Happy (ethical) hacking! 🐉