🛡️ Kali MCP Server

A production-ready MCP (Model Context Protocol) server running in a Kali Linux Docker container, providing AI assistants with access to a comprehensive security toolset.

📋 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) and allows AI to execute commands in a controlled environment with appropriate security measures.

✨ Features

• 🔒 Security Tools Access: Full access to Kali Linux security toolset through a controlled interface
• 🛡️ Command Validation: Commands are validated against an allowlist for security
• 🌐 Web Content Fetching: Retrieve and analyze web content
• 📊 Resource Information: Comprehensive system resource details and command examples
• 👤 Security Focus: Running as non-root user with appropriate permissions

🔧 Pre-installed Security Tools

• 🔍 Network Scanning: nmap, netcat
• 🕸️ Web Application Testing: nikto, gobuster, dirb
• 🧪 Penetration Testing: metasploit-framework
• 🔑 Credential Testing: hydra
• 💉 Data Extraction: sqlmap
• ℹ️ Information Gathering: whois, dig, host

🚀 Quick Start

🐳 Building and Running the Container

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

# Or manually:
# Build the Docker image
docker build -t kali-mcp-server .

# Run with default settings (SSE mode on port 8000)
docker run -p 8000:8000 kali-mcp-server

🔌 Connecting to Claude Desktop

1. Edit your Claude Desktop config file:

   • Location: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Add this configuration:

     {
       "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 the connection with a simple command:

   /run nmap -F localhost
   

🛠️ Available MCP Tools

The server provides several tools through the MCP protocol:

💻 run - Execute Commands

Run security tools and commands in the Kali Linux environment.

/run nmap -F localhost

Commands are validated against an allowlist for security. Long-running commands will be executed in the background with results saved to an output file.

🌐 fetch - Retrieve Web Content

Fetch and analyze web content from specified URLs.

/fetch https://example.com

📈 resources - List Available Resources

Get information about the system and available commands. (The AI can use these resources to run the commands on you behalf using Natural Language.)

/resources

🚀 vulnerability_scan - Automated Vulnerability Assessment

Perform automated vulnerability assessment with multiple tools.

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

Scan Types:

• quick: Fast scan with nmap and nikto
• comprehensive: Full scan with multiple tools
• web: Web-focused vulnerability assessment
• network: Network-focused vulnerability assessment

🌐 web_enumeration - Web Application Discovery

Perform comprehensive web application discovery and enumeration.

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

Enumeration Types:

• basic: Basic web enumeration with nikto and gobuster
• full: Comprehensive enumeration including vhost discovery
• aggressive: Aggressive enumeration with SQL injection testing

🔍 network_discovery - Network Reconnaissance

Perform multi-stage network reconnaissance and discovery.

/network_discovery target=192.168.1.0/24 discovery_type=comprehensive
/network_discovery target=example.com discovery_type=stealth

Discovery Types:

• quick: Quick network discovery
• comprehensive: Comprehensive network mapping
• stealth: Stealthy network reconnaissance

🔍 exploit_search - Exploit Database Search

Search for exploits using searchsploit and other exploit databases.

/exploit_search search_term=apache search_type=web
/exploit_search search_term=CVE-2021-44228 search_type=all

Search Types:

• all: Search all exploit types
• web: Web application exploits
• remote: Remote exploits
• local: Local exploits
• dos: Denial of service exploits

💾 save_output - Save Content to File

Save content to a timestamped file for evidence collection.

/save_output content="Scan results here" filename=my_scan category=scan
/save_output content="Enumeration data" category=enum

Categories:

• general: General content (default)
• scan: Vulnerability scan results
• enum: Enumeration results
• evidence: Evidence collection

📋 create_report - Generate Structured Reports

Generate a structured report from findings.

/create_report title="Security Assessment Report" findings="Vulnerabilities found..." report_type=markdown
/create_report title="Network Scan Results" findings="Open ports..." report_type=json

Report Types:

• markdown: Markdown format (default)
• text: Plain text format
• json: JSON format

🔍 file_analysis - Analyze Files

Analyze a file using various tools (file type, strings, hash).

/file_analysis filepath=./suspicious_file
/file_analysis filepath=/path/to/downloaded/file

Analysis includes:

• File type detection
• String extraction
• SHA256 hash
• File metadata
• Content preview

📥 download_file - Download Files

Download a file from a URL and save it locally.

/download_file url=https://example.com/file.txt filename=downloaded_file
/download_file url=https://example.com/script.sh

Features:

• Automatic filename extraction from URL
• SHA256 hash generation
• Content-type detection
• Safe filename sanitization

🗂️ session_create - Create New Session

Create a new pentest session with name, description, and target.

/session_create session_name="web_app_test" description="Web application security assessment" target="example.com"
/session_create session_name="network_scan" target="192.168.1.0/24"

Features:

• Session metadata storage
• Automatic session activation
• Organized file structure

📋 session_list - List Sessions

List all pentest sessions with metadata and status.

/session_list

Shows:

• All available sessions
• Active session indicator
• Session descriptions and targets
• Creation dates and history counts

🔄 session_switch - Switch Sessions

Switch to a different pentest session.

/session_switch session_name="web_app_test"

Features:

• Validates session existence
• Updates active session
• Shows session details after switch

📊 session_status - Session Status

Show current session status and summary.

/session_status

Shows:

• Active session details
• Session metadata
• File count and history
• Recent activity

🗑️ session_delete - Delete Session

Delete a pentest session and all its evidence.

/session_delete session_name="old_session"

Safety Features:

• Cannot delete active session
• Confirms deletion with session details
• Removes all session files and evidence

📜 session_history - Session History

Show command/evidence history for the current session.

/session_history

Shows:

• Chronological history of activities
• Action types and timestamps
• Session-specific evidence tracking

Enhanced Web Application Testing Tools

🕷️ Spider Website

Comprehensive web crawling and spidering using gospider.

/spider_website url=https://example.com depth=2 threads=10

Parameters:

• url (required): Target URL to spider
• depth (optional): Crawling depth (default: 2)
• threads (optional): Number of concurrent threads (default: 10)

📝 Form Analysis

Discover and analyze web forms for security testing.

/form_analysis url=https://example.com scan_type=comprehensive

Parameters:

• url (required): Target URL to analyze
• scan_type (optional): Type of analysis - "basic", "comprehensive", "aggressive" (default: "comprehensive")

📋 Header Analysis

Analyze HTTP headers for security information and misconfigurations.

/header_analysis url=https://example.com include_security=true

Parameters:

• url (required): Target URL to analyze
• include_security (optional): Include security header analysis (default: true)

🔐 SSL Analysis

Perform SSL/TLS security assessment using testssl.sh.

/ssl_analysis url=example.com port=443

Parameters:

• url (required): Target URL to analyze
• port (optional): SSL port (default: 443)

🔍 Subdomain Enumeration

Perform subdomain enumeration using multiple tools (subfinder, amass, waybackurls).

/subdomain_enum url=example.com enum_type=comprehensive

Parameters:

• url (required): Target domain to enumerate
• enum_type (optional): Type of enumeration - "basic", "comprehensive", "aggressive" (default: "comprehensive")

🔍 Web Audit

Perform comprehensive web application security audit.

/web_audit url=https://example.com audit_type=comprehensive

Parameters:

• url (required): Target URL to audit
• audit_type (optional): Type of audit - "basic", "comprehensive", "aggressive" (default: "comprehensive")

Tools Used in Web Audit:

• Nikto (web vulnerability scanner)
• Gobuster (directory/vhost enumeration)
• SQLMap (SQL injection testing)
• Dirb (directory enumeration)
• TestSSL.sh (SSL/TLS analysis)
• Curl (header analysis)

Session Management Tools

⚠️ Troubleshooting

🔌 Connection Issues

• Ensure port 8000 is available on your machine
• Check that the Docker container is running: docker ps
• Verify the URL in Claude Desktop configuration matches the container's port

⚙️ Command Execution Problems

• If commands timeout, try running them in the background: command > output.txt &
• Use /resources to see examples of properly formatted commands
• For permission errors, ensure you're not trying to access protected system areas

🔒 Security Considerations

This container provides access to powerful security tools. Please observe the following:

• Use responsibly and only in controlled environments
• The container is designed to be run locally and should not be exposed to the internet
• Commands are validated against an allowlist for security
• The server runs as a non-root user inside the container
• Only use this tool for legitimate security testing with proper authorization

📋 Requirements

• Docker
• Claude Desktop or other SSE enabled MCP clients
• Port 8000 available on your host machine

👨‍💻 Development

🛠️ Setting Up a Development Environment

# Clone the repository
git clone https://github.com/yourusername/kali-mcp-server.git
cd kali-mcp-server

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install development dependencies
pip install -e ".[dev]"

🧪 Running Tests

# Run tests with the helper script
./run_tests.sh

# Or manually:
# Run all tests
pytest

# Run with coverage
pytest --cov=kali_mcp_server

🙏 Acknowledgements

• Kali Linux for their security-focused distribution
• Anthropic for Claude and the MCP protocol
• The open-source security tools community

---

<p align="center"> _{Built for security professionals and AI assistants} </p>