K-MCP: Kali Model Context Protocol Server

K-MCP is a powerful API bridge that connects AI assistants (like Claude, GPT, etc.) to a Kali Linux terminal, enabling AI-driven penetration testing, CTF solving, and security research.

🔍 Overview

K-MCP extends the capabilities of AI assistants by giving them direct access to the Kali Linux command line. This enables your AI partner to:

• Execute security tools like nmap, gobuster, sqlmap, etc.
• Interact with remote systems via SSH, Evil-WinRM, and similar tools
• Solve CTF challenges in real-time
• Help with machines from HackTheBox or TryHackMe
• Automate repetitive security tasks
• Assist during penetration tests

🚀 Key Features

• 🧠 AI Integration: Works with Claude Desktop, 5ire, and other MCP-enabled AI interfaces
• 🔧 Tool Access: Execute any Kali Linux security tool through a secure API
• 🔄 Interactive Shell Sessions: Maintains persistent interactive sessions for SSH, Evil-WinRM, etc.
• 🔍 Automatic Tool Detection: Intelligently detects and handles interactive vs. non-interactive tools
• 🔐 Security Focus: Purpose-built for penetration testers, CTF players, and security researchers
• 📝 Session Management: Track and manage multiple concurrent interactive sessions
• 🌐 Network Tools Support: Full support for tools that require continuous network connection

📋 Requirements

• Kali Linux or similar security-focused distribution
• Python 3.7+ on both server and client
• An MCP-compatible AI interface (Claude Desktop, 5ire, etc.)
• Network connectivity between the AI client and Kali server

🛠️ Installation

1. On Your Kali Linux Machine

# Clone the repository
git clone https://github.com/YOUR-USERNAME/K-MCP.git

# Navigate to project directory
cd K-MCP

#Install necessary dependencies
pip install -r requirements.txt

# Start the Kali server
python3 kali_server.py

2: On Your Client Machine (Windows/Linux/Mac)

# Navigate to project directory
cd K-MCP

#Install necessary dependencies
pip install -r requirements.txt

#Edit the mcp_server.py file and change the ip
DEFAULT_KALI_SERVER = "http://XXX.XXX.XX.XX:5000" # change to your linux IP

# Run the MCP client, checking connectionto to your Kali server ( test purposes only ).You don't need to keep running this file.
python mcp_server.py
 

3. Configure Claude Desktop

Edit C:\\Users\\USERNAME\\AppData\\Roaming\\Claude\\claude_desktop_config.json:

{
    "mcpServers": {
        "kali_mcp": {
            "command": "python",
            "args": [
                "E:\\\\Paste_your_path_to_code\\\\mcp_server.py"
            ]
        }
    }
}

4: Run the claude desktop

Example Conversations with Claude

1. Basic Network Reconnaissance

User: Can you help me scan the target 192.168.1.100?

Claude: I'll help you perform a basic network reconnaissance. Let's start with a quick port scan to identify open services.

[Claude executes nmap_scan]
nmap_scan(
    target="192.168.1.100",
    scan_type="-sV",
    ports="1-1000",
    additional_args="-T4"
)

[After receiving results]
I see several open ports. Let's check the web server on port 80 in more detail.

[Claude executes gobuster_scan]
gobuster_scan(
    url="http://192.168.1.100",
    mode="dir",
    wordlist="/usr/share/wordlists/dirb/common.txt",
    additional_args="-x php,html,txt"
)

2. Web Application Testing

User: I found a login page at http://192.168.1.100/login.php. Can you help test it?

Claude: I'll help you test the login page for common vulnerabilities. Let's start with SQL injection testing.

[Claude executes sqlmap_scan]
sqlmap_scan(
    url="http://192.168.1.100/login.php",
    data="username=admin&password=test",
    additional_args="--batch --level=5 --risk=3"
)

[After receiving results]
I see some potential SQL injection points. Let's also check for common directories that might reveal more information.

[Claude executes nikto_scan]
nikto_scan(
    target="http://192.168.1.100",
    additional_args="-h"
)

3. Windows Machine Enumeration

User: I found a Windows machine at 192.168.1.100. Can you help enumerate it?

Claude: I'll help you enumerate the Windows machine using multiple tools. Let's start with a basic Windows enumeration.

[Claude executes enum4linux_scan]
enum4linux_scan(
    target="192.168.1.100",
    additional_args="-a"
)

💻 Usage Examples

Running Security Tools

K-MCP lets your AI execute any Kali Linux tool directly:

execute_command("nmap -sV -p- 10.10.10.10")
execute_command("gobuster dir -u http://target.com -w /usr/share/wordlists/dirb/common.txt")
execute_command("sqlmap -u 'http://target.com/page.php?id=1' --dbs")

Working with Interactive Tools

Interactive tools are automatically detected and handled:

execute_command("ssh [email protected]")
execute_command("evil-winrm -i 10.129.27.195 -u htb-student -p 'Password123!'")
execute_command("mysql -u root -p")

The system will:

1. Recognize these as interactive commands
2. Create a persistent session
3. Return a session ID for further interaction

Interactive Session Management

Once a session is created:

# Send a command to the session
interactive_send(session_id="your-session-id", command="whoami")

# Read output without sending a command
interactive_read(session_id="your-session-id")

# Close the session when done
interactive_close(session_id="your-session-id")

# List all active sessions
list_active_sessions()

Using Evil-WinRM Helper

For convenience with Evil-WinRM:

evil_winrm_connect(
    ip="10.129.27.195", 
    username="htb-student", 
    password="Password123!"
)

🔐 Security Considerations

• This tool enables remote command execution on your system
• Only use on secure networks or with proper network isolation
• Consider implementing authentication for the API
• Review all commands before allowing AI to execute them
• Designed for educational and professional security testing - use responsibly

🛤️ Advanced Use Cases

K-MCP enables AI to assist with many security tasks:

• Network Discovery & Enumeration: Using nmap, enum4linux, and netcat
• Web Application Testing: Using gobuster, sqlmap, nikto, etc.
• Windows Domain Testing: Using impacket, CrackMapExec, and Evil-WinRM
• Password Attacks: Using hydra, john, hashcat, etc.
• Forensic Analysis: Using volatility, autopsy, and other tools
• Exploit Development: For researching, modifying, and testing exploits
• CTF Challenges: For real-time assistance in solving CTF tasks

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs and suggest features
• Submit pull requests
• Improve documentation
• Share usage examples

⚠️ Disclaimer

K-MCP is intended solely for educational and authorized testing purposes. Any misuse of the information or tools provided — including unauthorized access, exploitation, or malicious activity — is strictly prohibited. The authors assume no responsibility for misuse.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgements

• Special thanks to the Kali Linux team for their amazing security distribution