WilliamSchweitzer/kali-mcp-server

Kali Security Tools MCP Server

A Model Context Protocol (MCP) server that provides educational WiFi testing and network security analysis tools using Kali Linux utilities.

Purpose

This MCP server provides a secure interface for AI assistants to help with legitimate network security testing and education on your own networks and devices only.

⚠️ IMPORTANT LEGAL NOTICE

This tool is for EDUCATIONAL PURPOSES ONLY. You may only use these tools on:

• Your own wireless networks
• Networks you have explicit written permission to test
• Isolated lab environments

Unauthorized network testing is illegal and unethical. Always comply with local laws and regulations.

TODO

• Add Fluxion Installer Script to Dockerfile
• Add Fluxion MCP Tools to kali_server.py MCP Server

Features

Current Implementation

• list_network_interfaces - List all network interfaces on the system
• check_wireless_card - Check if an interface supports monitor mode
• enable_monitor_mode - Enable monitor mode for packet capture
• disable_monitor_mode - Return interface to managed mode
• scan_wifi_networks - Scan for nearby WiFi networks
• change_mac_address - Change MAC address for privacy testing
• test_packet_injection - Test if card supports packet injection
• capture_handshake - Capture WPA handshake for testing
• deauth_client - Send deauthentication packets for testing
• network_info - Get current network configuration

Prerequisites

• Docker Desktop with MCP Toolkit enabled
• Docker MCP CLI plugin (docker mcp command)
• A USB WiFi adapter that supports monitor mode (recommended)
• Understanding of network security concepts
• Legal authorization to test target networks

Installation

See the step-by-step instructions provided with the files.

Configuration

The server uses these environment variables:

• WIFI_INTERFACE - Default wireless interface (default: wlan0)
• TARGET_MAC - Default target BSSID for testing
• EDUCATIONAL_MODE - Enable/disable sensitive features (default: true)

Usage Examples

In Claude Desktop, you can ask:

• "List all network interfaces on the system"
• "Check if wlan0 supports monitor mode"
• "Enable monitor mode on wlan0"
• "Scan for WiFi networks nearby"
• "Change the MAC address of wlan0 to random"
• "Test if wlan0mon supports packet injection"
• "Capture a handshake from my router at XX:XX:XX:XX:XX:XX on channel 6"
• "Send 5 deauth packets to my test network"
• "Show current network configuration"
• "Disable monitor mode and return to normal"

Architecture

Claude Desktop → MCP Gateway → Kali MCP Server → Kali Tools
                                        ↓
                              (aircrack-ng, macchanger, etc.)

Development

Local Testing

# Set environment variables for testing
export WIFI_INTERFACE="wlan0"
export TARGET_MAC="00:11:22:33:44:55"
export EDUCATIONAL_MODE="true"

# Run directly
python3 kali_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python3 kali_server.py

Adding New Tools

1. Add the function to kali_server.py
2. Decorate with @mcp.tool()
3. Update the catalog entry with the new tool name
4. Rebuild the Docker image

Troubleshooting

Tools Not Appearing

• Verify Docker image built successfully
• Check catalog and registry files
• Ensure Claude Desktop config includes custom catalog
• Restart Claude Desktop

Permission Errors

• Ensure Docker container has proper capabilities
• Check sudo configuration in Dockerfile
• Verify interface names are correct

Monitor Mode Issues

• Not all WiFi adapters support monitor mode
• USB adapters often work better than built-in
• Check with iw list for supported modes

No Networks Found

• Ensure interface is up: ip link set wlan0 up
• Check if monitor mode is properly enabled
• Verify no interfering processes with airmon-ng check

Security Considerations

• All operations require explicit user commands
• Educational mode flag restricts sensitive operations
• Running as non-root with specific sudo permissions
• Input sanitization prevents command injection
• No automatic or background scanning
• All actions are logged for accountability

Recommended WiFi Adapters

For best results, use adapters with these chipsets:

• Atheros AR9271 (TP-Link TL-WN722N v1)
• Ralink RT3070 (Alfa AWUS036NH)
• Realtek RTL8812AU (Alfa AWUS036ACH)

Educational Resources

Learn more about WiFi security:

• Aircrack-ng Documentation: https://www.aircrack-ng.org/documentation.html
• WiFi Security Fundamentals: https://www.wi-fi.org/discover-wi-fi/security
• Ethical Hacking Courses: Consider taking certified courses (CEH, OSCP)

License

MIT License

Disclaimer

This tool is provided as-is for educational purposes. The authors are not responsible for any misuse or damage caused by this tool. Always ensure you have proper authorization before testing any network.