AlessandroAnnini/kali-mcp-server

Kali Linux MCP Server

A professional-grade Model Context Protocol (MCP) server providing secure access to Kali Linux security tools through containerized execution. Designed for use with Claude Desktop, Cursor, and other MCP-compatible clients.

Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Available Tools
• Usage Examples
• Security Considerations
• Development
• Legal Notice

Features

Core Capabilities

• Containerized Security Tools - Isolated Docker environment for safe execution
• Network Security Testing - Nmap, Nikto, DIRB, and custom command execution
• WiFi Security Auditing - Monitor mode, packet capture, WPA/WPA2 attacks
• JWT Security Testing - Token analysis and vulnerability detection
• VPN Integration - Built-in Mullvad VPN support for anonymous testing
• Environment-Based Configuration - Secure credential management via .env files

Security Features

• Containerized execution with isolated environments
• Configurable network access (bridge/host/none modes)
• Privileged mode support for WiFi operations
• Command whitelisting and input validation
• Automatic cleanup after operations
• VPN anonymity for professional assessments

Requirements

• Python 3.10+ (required by MCP SDK)
• Docker (for containerized Kali tools)
• uv package manager
• Mullvad VPN subscription (optional, for VPN features)
• Java Runtime (automatically installed for OWASP ZAP)
• Node.js/npm (automatically installed for retire.js)

Installation

Step 1: Install Dependencies

cd /path/to/kali-mcp-server
uv sync

Step 2: Build Docker Image

docker build -t kali-mcp:latest .

This will install:

• Kali Linux base system
• Network security tools (nmap, nikto, dirb)
• Web application scanners (sqlmap, OWASP ZAP, nuclei)
• SSL/TLS testing (testssl.sh)
• JavaScript security scanner (retire.js)
• WiFi security tools (airmon-ng, reaver, wifite, aircrack-ng)
• Mullvad VPN client
• Python libraries for JWT and security testing
• Java runtime and Node.js for modern tools

Step 3: Configure Mullvad VPN (Optional)

Edit the .env file with your Mullvad credentials:

# Required: Your Mullvad account number
MULLVAD_ACCOUNT_NUMBER=YOUR_16_DIGIT_ACCOUNT_NUMBER

# Optional: Default server location (default: se)
MULLVAD_DEFAULT_SERVER=se

# Optional: Default protocol (default: wireguard)
MULLVAD_DEFAULT_PROTOCOL=wireguard

Get your Mullvad account from mullvad.net

Configuration

MCP Client Setup

Add the following to your MCP client configuration file:

{
  "mcpServers": {
    "kali-linux": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/kali-mcp-server",
        "python",
        "src/kali_mcp_server/mcp_server.py"
      ]
    }
  }
}

Important: Replace /absolute/path/to/kali-mcp-server with your actual project path.

Configuration File Locations

Alternative VPN Configuration Methods

Method 1: Environment Variables

export MULLVAD_ACCOUNT_NUMBER="YOUR_16_DIGIT_ACCOUNT"
export MULLVAD_DEFAULT_SERVER="se"
export MULLVAD_DEFAULT_PROTOCOL="wireguard"

Method 2: Runtime Configuration Use the vpn_configure_account tool after the server starts.

Method 3: Docker Image Edit the Dockerfile to bake credentials into the image (not recommended for production).

Available Tools

Network Security Tools

nmap_scan

Perform network scanning and port discovery.

Parameters:

• target (required) - Target IP/hostname/network
• scan_type (optional) - Scan type: quick, full, or stealth
• ports (optional) - Port range (e.g., 80,443 or 1-1000)

nikto_scan

Web application vulnerability scanner (legacy tool).

Parameters:

• target (required) - Target URL
• options (optional) - Additional Nikto command-line options

dirb_scan

Directory and file brute-forcing tool.

Parameters:

• target (required) - Target URL
• wordlist (optional) - Path to wordlist file

Web Application Security Tools

sqlmap_scan

Automated SQL injection detection and exploitation tool.

Parameters:

• target (required) - Target URL
• level (optional) - Test thoroughness 1-5 (default: 1)
• risk (optional) - Risk level 1-3 (default: 1)
• data (optional) - POST data for testing forms

Use Cases:

• Detect SQL injection vulnerabilities in web applications
• Test GET and POST parameters
• Extract database contents for authorized testing
• Identify database type and version

zap_scan

OWASP ZAP - Modern web application security scanner.

Parameters:

• target (required) - Target URL
• scan_type (optional) - baseline (quick), full (thorough), or api (REST APIs)

Use Cases:

• Comprehensive vulnerability scanning for modern web apps
• Automated testing of SPAs (React, Vue, Angular)
• API security testing with OpenAPI/Swagger support
• Active and passive vulnerability detection
• Better alternative to Nikto for modern applications

nuclei_scan

Fast template-based vulnerability scanner with 5000+ checks.

Parameters:

• target (required) - Target URL
• templates (optional) - Template tags (e.g., cves,misconfigurations,exposures)
• severity (optional) - Filter by severity: critical,high,medium,low,info

Use Cases:

• CVE detection and exploitation
• Misconfiguration detection
• Exposed admin panels and sensitive files
• Security header validation
• Custom template-based checks

testssl_scan

Comprehensive SSL/TLS configuration and vulnerability scanner.

Parameters:

• target (required) - Target hostname:port or URL
• checks (optional) - Specific check type

Use Cases:

• Test HTTPS/TLS configuration
• Detect SSL/TLS vulnerabilities (Heartbleed, POODLE, etc.)
• Analyze cipher suite strength
• Certificate validation
• Perfect for testing local dev servers with HTTPS

retirejs_scan

Scan for vulnerable and outdated JavaScript libraries.

Parameters:

• target (required) - Target URL or local path

Use Cases:

• Identify vulnerable JavaScript libraries (jQuery, Angular, etc.)
• Detect outdated npm packages
• Find known CVEs in client-side dependencies
• Security auditing of third-party scripts

security_headers_check

Analyze HTTP security headers configuration.

Parameters:

• target (required) - Target URL

Checks For:

• Content-Security-Policy - XSS and injection protection
• Strict-Transport-Security - HTTPS enforcement
• X-Frame-Options - Clickjacking protection
• X-Content-Type-Options - MIME sniffing prevention
• Referrer-Policy - Referrer information control
• Permissions-Policy - Browser feature control

Use Cases:

• Validate security header implementation
• Quick security posture assessment
• Development/staging environment validation
• Production deployment verification

VPN Management Tools

vpn_connect

Connect to Mullvad VPN with optional server selection.

Parameters:

• server (optional) - Server location (e.g., se, nl ams, us-nyc-wg-301)
• protocol (optional) - VPN protocol: wireguard or openvpn

vpn_disconnect

Disconnect from Mullvad VPN.

vpn_status

Check VPN connection status and details.

Parameters:

• verbose (optional) - Show detailed status information

JWT Security Tools

jwt_decode

Decode and analyze JWT token structure.

Parameters:

• token (required) - JWT token to decode
• verify (optional) - Attempt signature verification
• secret (optional) - Secret key for verification

jwt_security_test

Test JWT tokens for common security vulnerabilities.

Parameters:

• token (required) - JWT token to test
• endpoint (optional) - API endpoint to test against

Vulnerability Tests:

• None algorithm bypass attacks
• Weak secret brute-forcing
• Algorithm confusion attacks
• Token manipulation attempts
• Signature verification bypass

WiFi Security Tools

Note: WiFi tools are available in the Docker image but not yet exposed as MCP tools. They can be accessed via the custom_command tool if implemented.

Available WiFi capabilities:

• Monitor mode activation/deactivation
• Network scanning and discovery
• WPA/WPA2 handshake capture
• WPS vulnerability testing
• MAC address spoofing
• Packet injection and analysis

Usage Examples

Web Application Security Testing (Local Development)

// 1. Check security headers first
security_headers_check({
  target: 'http://localhost:3000',
});

// 2. Scan for vulnerable JavaScript libraries
retirejs_scan({
  target: 'http://localhost:3000',
});

// 3. Test for SQL injection vulnerabilities
sqlmap_scan({
  target: 'http://localhost:3000/api/users?id=1',
  level: 3,
  risk: 2,
});

// 4. Test POST forms for SQL injection
sqlmap_scan({
  target: 'http://localhost:3000/login',
  data: 'username=admin&password=test',
  level: 2,
});

// 5. Comprehensive web app scan
zap_scan({
  target: 'http://localhost:3000',
  scan_type: 'baseline',
});

// 6. Fast vulnerability detection with Nuclei
nuclei_scan({
  target: 'http://localhost:3000',
  templates: 'cves,misconfigurations,exposures',
  severity: 'critical,high',
});

// 7. Test HTTPS configuration (if using SSL)
testssl_scan({
  target: 'https://localhost:8443',
});

Network Reconnaissance

// Quick port scan
nmap_scan({
  target: '192.168.1.0/24',
  scan_type: 'quick',
});

// Full scan with OS detection
nmap_scan({
  target: 'example.com',
  scan_type: 'full',
  ports: '1-65535',
});

// Web vulnerability scan
nikto_scan({
  target: 'https://example.com',
});

// Directory enumeration
dirb_scan({
  target: 'https://example.com',
  wordlist: '/usr/share/dirb/wordlists/common.txt',
});

VPN-Protected Testing

// Connect to VPN before testing
vpn_connect({
  server: 'se got',
  protocol: 'wireguard',
});

// Verify VPN connection
vpn_status({ verbose: true });

// Perform anonymous testing
nmap_scan({
  target: 'authorized-target.com',
  scan_type: 'stealth',
});

// Disconnect when done
vpn_disconnect();

JWT Security Assessment

// Decode JWT token
jwt_decode({
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  verify: true,
  secret: 'suspected-secret',
});

// Security vulnerability testing
jwt_security_test({
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  endpoint: 'https://api.example.com/protected',
});

Professional Security Workflow

// 1. Establish anonymous connection
vpn_connect({ server: 'se got' });
vpn_status({ verbose: true });

// 2. Initial reconnaissance
nmap_scan({
  target: 'authorized-target.com',
  scan_type: 'stealth',
  ports: '1-10000',
});

// 3. Web application security testing
// a. Modern vulnerability scan
zap_scan({
  target: 'https://authorized-target.com',
  scan_type: 'baseline',
});

// b. Fast CVE and misconfiguration detection
nuclei_scan({
  target: 'https://authorized-target.com',
  templates: 'cves,misconfigurations,exposures',
  severity: 'critical,high',
});

// c. Security headers check
security_headers_check({
  target: 'https://authorized-target.com',
});

// d. Check for vulnerable JavaScript libraries
retirejs_scan({
  target: 'https://authorized-target.com',
});

// 4. Database security testing
sqlmap_scan({
  target: 'https://authorized-target.com/api/products?id=1',
  level: 3,
  risk: 2,
});

// 5. SSL/TLS security analysis
testssl_scan({
  target: 'authorized-target.com:443',
});

// 6. API and JWT security testing
jwt_security_test({
  token: 'captured-jwt-token',
  endpoint: 'https://api.authorized-target.com/v1/user',
});

// 7. Switch VPN location if needed
vpn_connect({ server: 'nl ams' });

// 8. Additional testing from new IP
nmap_scan({
  target: 'authorized-target.com',
  scan_type: 'full',
});

// 9. Clean disconnect
vpn_disconnect();

Complete Local Development Security Audit

// Comprehensive security check for your local web application
const target = 'http://localhost:3000';

// Step 1: Quick security posture
security_headers_check({ target });

// Step 2: Check for vulnerable dependencies
retirejs_scan({ target });

// Step 3: SQL injection testing
sqlmap_scan({
  target: `${target}/api/search?q=test`,
  level: 2,
  risk: 1,
});

// Step 4: Comprehensive vulnerability scan
zap_scan({
  target,
  scan_type: 'baseline',
});

// Step 5: Template-based checks
nuclei_scan({
  target,
  templates: 'misconfigurations,exposures',
  severity: 'medium,high,critical',
});

// Step 6: If using HTTPS locally
testssl_scan({
  target: 'https://localhost:8443',
});

Security Considerations

Legal and Ethical Guidelines

CRITICAL: Only use this tool on systems you own or have explicit written permission to test. Unauthorized access to computer systems is illegal in most jurisdictions.

VPN Security Best Practices

1. Credential Protection - Never commit .env files to version control
2. Connection Verification - Always verify VPN status before sensitive operations
3. Kill Switch - Use lockdown mode to prevent traffic leaks
4. DNS Leak Prevention - Verify DNS queries route through VPN
5. Operational Security - Assume all testing activities may be logged

Container Security

1. Minimal Privileges - Uses --cap-add NET_ADMIN and --cap-add NET_RAW instead of --privileged for better security
2. Host Network Access - Network scans and VPN operations use host network mode only when needed
3. Resource Limits - Consider implementing Docker resource constraints
4. Image Security - Regularly update the Docker image for security patches
5. Container Isolation - Non-privileged operations run in bridge network mode with minimal capabilities

WiFi Testing Warnings

1. Legal Compliance - WiFi testing may violate laws in your jurisdiction
2. Network Disruption - Attacks can disrupt legitimate network services
3. Interference - Monitor mode may interfere with your own connectivity
4. Data Handling - Captured handshakes contain sensitive information

Professional Usage Guidelines

1. Documentation - Maintain detailed logs of all security testing activities
2. Authorization - Keep written authorization for all penetration tests
3. Scope Adherence - Only test systems explicitly included in scope
4. Responsible Disclosure - Report vulnerabilities through proper channels
5. Evidence Chain - Document VPN usage for legal compliance

Development

Project Structure

kali-mcp-server/
├── src/
│   └── kali_mcp_server/
│       ├── __init__.py
│       ├── mcp_server.py           # Main MCP server (clean coordinator)
│       ├── core/
│       │   ├── __init__.py
│       │   └── docker_executor.py  # Reusable Docker execution engine
│       └── tools/
│           ├── __init__.py
│           ├── network_tools.py    # Nmap, Nikto, DIRB
│           ├── web_tools.py        # SQLMap, ZAP, Nuclei, testssl, retire.js
│           ├── vpn_tools.py        # Mullvad VPN management
│           └── jwt_tools.py        # JWT security testing
├── Dockerfile                       # Kali Linux container definition
├── pyproject.toml                   # Python dependencies
├── .env                            # Environment configuration (git-ignored)
├── .env.example                    # Environment template
└── README.md                       # This file

Architecture Principles

The server follows DRY (Don't Repeat Yourself) and KISS (Keep It Simple, Stupid) principles:

• Modular Design - Each tool category in its own module
• Composition Over Inheritance - Functions, not complex class hierarchies
• Single Responsibility - One Docker executor used by all tools
• Comprehensive Documentation - Every function has detailed Python docstrings

Development Commands

# Install development dependencies
uv sync --dev

# Format code
uv run black .

# Lint code
uv run ruff check .

# Run tests (if available)
uv run pytest

# Test server locally
uv run python src/kali_mcp_server/mcp_server.py

Adding New Tools

The modular architecture makes adding new tools straightforward:

1. Create tool module - Add function to appropriate module in tools/

   • Network tools → network_tools.py
   • Web security → web_tools.py
   • VPN/anonymity → vpn_tools.py
   • Authentication → jwt_tools.py
   • New category → Create new module file

2. Export function - Add to tools/__init__.py

3. Register tool - Add to TOOL_DEFINITIONS and TOOL_HANDLERS in mcp_server.py

4. Add documentation - Include Python docstrings with:

   • Description of functionality
   • Args with types and descriptions
   • Returns specification
   • Usage examples

5. Test thoroughly - Verify in isolated environment

Example: Adding a new network tool:

# In tools/network_tools.py
async def run_masscan(args: Dict[str, Any]) -> Dict[str, Any]:
    """Execute Masscan port scanner.

    Args:
        args: Dictionary containing target and rate parameters

    Returns:
        Dictionary with scan results
    """
    target = args["target"]
    rate = args.get("rate", 1000)
    cmd = ["masscan", target, "-p1-65535", f"--rate={rate}"]
    return await execute_in_container(cmd, privileged=True)

Docker Image Customization

The Dockerfile can be customized to add additional tools:

# Add custom tools
RUN apt-get update && apt-get install -y \
    your-custom-tool \
    another-tool \
    && rm -rf /var/lib/apt/lists/*

# Add Python packages
RUN pip3 install --no-cache-dir --break-system-packages \
    your-python-package

Rebuild the image after modifications:

docker build -t kali-mcp:latest .

Troubleshooting

Server Not Starting

Problem: "No tools, prompts, or resources" error in MCP client

Solution: Ensure you're using the --directory flag in your MCP configuration:

"args": ["run", "--directory", "/absolute/path/to/project", "python", "src/kali_mcp_server/mcp_server.py"]

Docker Connection Issues

Problem: Cannot connect to Docker daemon

Solution:

# Start Docker service
sudo systemctl start docker

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

VPN Connection Failures

Problem: VPN fails to connect

Solutions:

• Verify Mullvad account number in .env file
• Check Mullvad subscription is active
• Ensure privileged Docker mode is enabled
• Verify host network access is available

Module Import Errors

Problem: ModuleNotFoundError when starting server

Solution:

# Reinstall dependencies
uv sync

# Verify uv is using correct Python version
uv run python --version  # Should be 3.10+

Nmap Permission Errors

Problem: Operation not permitted when running nmap scans

Solution: This is fixed in v1.0.0 with proper capability management. The server now uses:

• --cap-add NET_ADMIN for network administration
• --cap-add NET_RAW for raw packet access
• --network host for network scanning operations

Instead of the insecure --privileged flag. If you still experience issues:

# Verify Docker image is updated
docker images | grep kali-mcp

# Rebuild if needed
docker build -t kali-mcp:latest .

# Test manually
docker run --rm --network host --cap-add NET_ADMIN --cap-add NET_RAW \
  kali-mcp:latest nmap -F 192.168.1.1

Reference: Based on Docker MCP Tutorial Issue #7

Contributing

Contributions are welcome! Please ensure:

1. Code follows existing style (use black and ruff)
2. All security tools are properly containerized
3. Documentation is updated for new features
4. Testing is performed in isolated environments

License

This project is provided as-is for educational and authorized security testing purposes only.

Legal Notice

WARNING: This tool is designed for authorized security testing only.

Unauthorized access to computer systems is illegal. Users are responsible for:

• Obtaining proper authorization before testing
• Complying with all applicable laws and regulations
• Using the tool ethically and responsibly
• Maintaining confidentiality of discovered vulnerabilities

The authors and contributors assume no liability for misuse of this tool.

Acknowledgments

• Kali Linux - Security testing platform
• Mullvad VPN - Privacy-focused VPN service
• Model Context Protocol - Anthropic's MCP standard
• Security Community - For tools and methodologies

Resources

• Mullvad CLI Documentation
• MCP Protocol Specification
• Kali Linux Documentation
• Docker Security Best Practices

Version: 1.0.0 Last Updated: October 21, 2024 Status: Production Ready - Modular Architecture

Recent Updates

• ✅ v1.0.0 (Oct 21, 2024) - Complete refactoring with modular architecture
  • Modular tool organization (DRY & KISS principles)
  • Improved Docker security (minimal capabilities instead of --privileged)
  • Comprehensive Python docstrings for all functions
  • Composition-based design for maintainability
  • Fixed nmap execution with proper NET_ADMIN/NET_RAW capabilities