# 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

```bash
# 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)

```bash
# 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`:

```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 user@10.10.10.10")
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