Kali Linux MCP Server

An MCP (Model Context Protocol) server that integrates Kali Linux security tools with AI assistants like Claude. This project enables security professionals to run penetration testing tools, vulnerability assessments, and generate reports through natural language commands.

Architecture

┌─────────────────┐      MCP Protocol      ┌─────────────────┐      SSH/RPC       ┌─────────────────┐
│                 │ ───────────────────▶   │                 │ ───────────────▶   │                 │
│  AI Assistant   │                        │   MCP Server    │                    │  Kali Linux     │
│  (Claude, etc)  │                        │  (This Project) │                    │  Security Tools │
│                 │ ◀───────────────────   │                 │ ◀───────────────   │                 │
└─────────────────┘    Structured Results  └─────────────────┘   Tool Output      └─────────────────┘

The server acts as a bridge between AI assistants and security tools. It receives natural language requests via MCP, translates them into tool commands, executes them on the Kali environment, and returns structured results.

This project bridges AI assistants with professional security tools. Instead of manually running nmap, sqlmap, or metasploit commands, you can describe what you want to do in plain English and let the AI handle the tool execution.

The server exposes 35+ security tools through the MCP protocol, covering:

• Reconnaissance and port scanning
• Web vulnerability testing (SQLi, XSS, etc.)
• Local network scanning and exploitation
• Metasploit framework integration
• Browser automation for JavaScript-heavy apps
• Automated report generation

Features

Reconnaissance & Scanning

• scan_website_comprehensive - Full vulnerability assessment covering 25+ attack vectors
• scan_ports - TCP/UDP port scanning with service detection
• enumerate_directories - Directory enumeration using Gobuster
• scan_ssl_tls - SSL/TLS configuration analysis

Injection Testing

• scan_injection_attacks - Comprehensive injection vulnerability scanning
• validate_sql_injection - SQL injection validation with proof of concept
• validate_xss - Cross-site scripting detection and validation

Network Security

• scan_local_network - Discover devices on local network (auto-detects range)
• discover_network_clients - ARP-based client discovery with MAC/vendor info
• get_wifi_passwords - Retrieve saved WiFi credentials (Linux/macOS)
• scan_host_vulnerabilities - Deep vulnerability scan on specific hosts
• exploit_smb - SMB vulnerability checks (EternalBlue, MS08-067)
• scan_wireless_networks - Scan nearby WiFi networks and security
• run_network_exploit - Brute force tools for SSH, FTP, RDP, VNC

Metasploit Integration

• connect_metasploit - Connect to Metasploit RPC server
• search_exploits - Search the exploit database
• run_exploit - Execute exploits against targets
• list_sessions - List active shells and meterpreter sessions
• run_auxiliary - Run scanner and fuzzer modules

Browser Automation

• scan_javascript_app - Analyze JavaScript-heavy applications
• capture_screenshot - Full page screenshots
• crawl_spa - Crawl Single Page Applications

Report Generation

• generate_pdf_report - Professional PDF vulnerability reports
• generate_html_report - Interactive HTML reports with filtering
• export_findings_json - Structured JSON export for integration

Project Structure

kali-linux-mcp/
├── main.py                 # MCP server entry point
├── tools/
│   ├── helpers.py          # Shared utilities
│   ├── reconnaissance.py   # Port/web scanning
│   ├── authentication.py   # Auth testing
│   ├── injection.py        # SQL/XSS testing
│   ├── access_control.py   # IDOR, path traversal
│   ├── network.py          # Local network scanning
│   ├── metasploit.py       # Metasploit integration
│   ├── browser.py          # Selenium automation
│   └── reports.py          # Report generation
├── tests/                  # Test suite (72 tests)
├── pyproject.toml
└── README.md

Installation

Prerequisites

• Python 3.12 or higher
• uv package manager
• Kali Linux (VM, Docker, or OrbStack)

Setup

git clone https://github.com/rifkyekayama/kali-linux-mcp.git
cd kali-linux-mcp
uv sync
uv run python main.py

Setting Up Kali Linux

You need a Kali Linux environment with security tools installed. Here are several options:

OrbStack (macOS)

If you're on macOS, OrbStack is the easiest way to run Kali:

# Install OrbStack
brew install orbstack

# Create Kali machine
orb create kali kali

# Enter the machine
orb -m kali

# Install security tools
sudo apt update && sudo apt upgrade -y
sudo apt install -y metasploit-framework nmap nikto sqlmap gobuster dirb hydra sslscan arp-scan

# Initialize and start Metasploit RPC
sudo msfdb init
msfrpcd -P yourpassword -S -a 0.0.0.0

Docker

docker pull kalilinux/kali-rolling
docker run -it --name kali -p 55553:55553 kalilinux/kali-rolling /bin/bash

# Inside container
apt update && apt install -y kali-linux-headless

VirtualBox / VMware

1. Download the Kali ISO from kali.org
2. Create a VM with at least 4GB RAM and 40GB disk
3. Use bridged networking for local network scanning
4. Install the security tools listed above

WSL2 (Windows)

wsl --install -d kali-linux

Then install tools inside Kali as shown above.

Claude Desktop Configuration

Add this to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kali-linux-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/kali-linux-mcp", "python", "main.py"]
    }
  }
}

Metasploit Connection

Start the RPC daemon on your Kali machine:

msfrpcd -P yourpassword -S -a 0.0.0.0 -p 55553

Then connect through the MCP tool using the Kali machine's IP address.

Example Prompts for AI Models

Once configured, you can use natural language to interact with security tools. Here are example prompts to get started:

Web Application Scanning

Comprehensive Web Vulnerability Assessment:

Run a comprehensive vulnerability scan on https://example.com and generate a PDF report with all findings.

Targeted Vulnerability Testing:

Test https://example.com/login for SQL injection vulnerabilities on the username and password parameters.

Check https://example.com for XSS vulnerabilities in all input fields and forms.

SSL/TLS Configuration Analysis:

Analyze the SSL/TLS configuration of https://example.com and identify any weak ciphers or outdated protocols.

Directory Enumeration:

Enumerate all directories and files on https://example.com using common wordlists.

JavaScript Application Testing:

Scan the JavaScript application at https://app.example.com for client-side vulnerabilities including DOM-based XSS and prototype pollution.

Web Exploitation

SQL Injection Exploitation:

Validate and exploit the SQL injection vulnerability at https://example.com/product?id=1 and extract the database schema.

Authentication Testing:

Test the authentication mechanism at https://example.com/login for weak password policies, session management issues, and account enumeration vulnerabilities.

Access Control Testing:

Test https://example.com/api/users for IDOR vulnerabilities by attempting to access user IDs from 1 to 100.

Comprehensive Web Exploitation:

Scan https://example.com for all injection vulnerabilities (SQL, NoSQL, command injection, template injection) and provide proof of concept for any findings.

Local Network Scanning

Network Discovery:

Scan my local network for all active devices and identify their operating systems and open ports.

Specific Network Range:

Scan the network range 192.168.1.0/24 for active hosts and enumerate all open ports on each device.

WiFi Security Analysis:

Scan for nearby wireless networks and analyze their security configurations.

ARP-based Discovery:

Use ARP scanning to discover all clients on the local network and identify their MAC addresses and vendors.

Network Exploitation

SMB Vulnerability Testing:

Check if the host 192.168.1.100 is vulnerable to EternalBlue (MS17-010) or other SMB exploits.

Service Bruteforce:

Perform an SSH brute force attack on 192.168.1.50 using common credentials.

Deep Host Vulnerability Scan:

Run a deep vulnerability scan on 192.168.1.100 and identify all potential security weaknesses.

Metasploit Operations

Exploit Search and Execution:

Connect to Metasploit, search for Apache Struts exploits, and show me the top 5 most relevant modules.

Use Metasploit to exploit the SMB vulnerability on 192.168.1.100 and establish a reverse shell session.

Auxiliary Modules:

Run the SSH version scanner auxiliary module against 192.168.1.0/24 to identify all SSH servers and their versions.

Report Generation

Multi-format Reporting:

Scan https://example.com comprehensively and generate both HTML and PDF reports with all vulnerabilities categorized by severity.

JSON Export for Integration:

Export all findings from the last scan to JSON format for integration with my vulnerability management system.

Combined Operations

Full Security Assessment:

Perform a complete security assessment of https://example.com including:
1. Port scanning and service enumeration
2. Web vulnerability testing (SQL injection, XSS, CSRF)
3. SSL/TLS configuration analysis
4. Directory enumeration
5. Authentication and access control testing
Then generate a comprehensive PDF report with remediation recommendations.

Network Penetration Test:

Conduct a penetration test on my local network (192.168.1.0/24):
1. Discover all active hosts
2. Scan for open ports and services
3. Check for SMB vulnerabilities
4. Test for weak SSH/FTP credentials
5. Generate a detailed report with findings

[!TIP] Be specific in your prompts. Include target URLs/IPs, parameter names, and desired output format for best results.

[!WARNING] Always ensure you have proper authorization before testing any system. Unauthorized security testing is illegal.

Testing

The project includes 72 unit tests with mocked subprocess calls:

# Run all tests
uv run pytest tests/ -v

# Run specific module tests
uv run pytest tests/test_network.py -v

# Run with coverage
uv add --dev pytest-cov
uv run pytest tests/ --cov=tools

Requirements

Python Dependencies

• mcp >= 1.26.0
• selenium >= 4.15.0
• webdriver-manager >= 4.0.0
• Pillow >= 10.0.0
• reportlab >= 4.0.0
• jinja2 >= 3.1.0
• pymetasploit3 >= 1.0.0

Kali Linux Tools

The following tools should be installed on your Kali machine:

• nmap (port scanning)
• nikto (web vulnerability scanner)
• sqlmap (SQL injection)
• gobuster (directory enumeration)
• hydra (password cracking)
• sslscan (SSL/TLS analysis)
• metasploit-framework
• arp-scan (network discovery)

Disclaimer

This tool is for authorized security testing only. Only use it on systems you own or have explicit written permission to test. Unauthorized access to computer systems is illegal.

License

MIT License - see LICENSE for details.

Contact

• GitHub: @rifkyekayama
• LinkedIn: Rifky Ekayama