Content
# 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
