MCP Server for Breaking Shyet - Diclaimer - This is a DEVKIT

A Model Context Protocol (MCP) server that connects Claude for Desktop with Kali Linux security tools, enabling AI-assisted penetration testing

Architecture

This project consists of two main components:

MCP Server (mcp_server.py): Implements the Model Context Protocol to connect Claude for Desktop with the Kali Linux tools API. It provides capabilities, prompts, and context to help Claude understand how to use the Kali tools effectively.
Kali Linux API Server (kali_api_server.py): A Flask application that provides API endpoints for executing various Kali Linux security tools. It handles the actual execution of commands and returns the results to the MCP server.

Claude for Desktop ←→ MCP Server ←→ Kali Linux API Server ←→ Kali Linux Tools

Features

Integration with popular Kali Linux security tools
Pre-defined pentesting prompts for common tasks
Contextual information about HackTheBox environments
Comprehensive debugging tools for troubleshooting

Prerequisites

Kali Linux (or other Linux distribution with security tools installed)
Python 3.8+
Claude for Desktop
The following Python packages (installed automatically in a virtual environment):
- Flask
- Requests
- psutil (for system diagnostics)

Installation

Option 1: Using the setup script (Recommended)

Clone this repository:

git clone https://github.com/yourusername/kali-mcp-server.git
cd kali-mcp-server

Run the setup script:
```
./setup.sh
```

Option 2: Manual setup

Clone this repository:

git clone https://github.com/yourusername/kali-mcp-server.git
cd kali-mcp-server

Create a virtual environment:
```
python3 -m venv venv
```
Activate the virtual environment:
```
source venv/bin/activate
```
Install dependencies:
```
pip install -r requirements.txt
```

Make the scripts executable:

chmod +x mcp_server.py kali_api_server.py run.py

Ensure required Kali Linux tools are installed

Make sure the relevant Kali Linux tools are installed on your system:

sudo apt update
sudo apt install nmap gobuster dirb nikto sqlmap metasploit-framework hydra john wpscan enum4linux

Usage

Using the run.py script (Recommended)

The easiest way to start both servers is using the run.py script:

./run.py

This will start both the API server and MCP server in separate terminals.

Additional options:

--api-port PORT: Specify the API server port (default: 5000)
--mcp-port PORT: Specify the MCP server port (default: 8080)
--background: Run both servers in the background
--setup: Set up or update the virtual environment
--debug: Enable debug mode with detailed logging and diagnostic endpoints

Starting servers manually

If you prefer to start the servers manually:

Start the Kali Linux API Server:

source venv/bin/activate
python kali_api_server.py

In a new terminal, start the MCP Server:

source venv/bin/activate
python mcp_server.py

Connect Claude for Desktop

Open Claude for Desktop
Configure it to use the MCP server at http://localhost:8080
Start a new conversation and begin your penetration testing

Configuring Claude for Desktop (Linux)

If you're using the unofficial Claude Desktop for Linux build:

Edit the MCP configuration file:

nano ~/.config/Claude/claude_desktop_config.json

Add your MCP server:

{
  "mcp_servers": [
    {
      "name": "Kali Linux Tools",
      "url": "http://localhost:8080",
      "enabled": true
    }
  ]
}

Save the file and restart Claude Desktop

Supported Tools

nmap: Network scanning and host discovery

{
  "target": "10.10.10.10",
  "scan_type": "-sV",
  "ports": "80,443,22",
  "additional_args": "-T4 --open"
}

gobuster: Directory and file brute forcing

{
  "url": "http://10.10.10.10",
  "mode": "dir",
  "wordlist": "/usr/share/wordlists/dirb/common.txt",
  "additional_args": "-x php,txt,html"
}

dirb: Web content scanner

{
  "url": "http://10.10.10.10",
  "wordlist": "/usr/share/wordlists/dirb/common.txt",
  "additional_args": "-r -z 10"
}

nikto: Web server scanner

{
  "target": "http://10.10.10.10",
  "additional_args": "-Tuning 123bx"
}

sqlmap: SQL injection testing

{
  "url": "http://10.10.10.10/page.php?id=1",
  "data": "username=test&password=test",
  "additional_args": "--batch --dbs"
}

metasploit: Exploitation framework

{
  "module": "exploit/multi/http/apache_struts2_content_type_rce",
  "options": {
    "RHOSTS": "10.10.10.10",
    "RPORT": "8080",
    "TARGETURI": "/struts2-showcase/"
  }
}

hydra: Password brute forcing

{
  "target": "10.10.10.10",
  "service": "ssh",
  "username": "admin",
  "password_file": "/usr/share/wordlists/rockyou.txt",
  "additional_args": "-e nsr"
}

john: Password cracking

{
  "hash_file": "/path/to/hashes.txt",
  "wordlist": "/usr/share/wordlists/rockyou.txt",
  "format": "md5crypt",
  "additional_args": "--rules=Jumbo"
}

wpscan: WordPress vulnerability scanner

{
  "url": "http://10.10.10.10",
  "additional_args": "--enumerate u,p,t"
}

enum4linux: Windows/Samba enumeration

{
  "target": "10.10.10.10",
  "additional_args": "-a"
}

Example Workflow for HTB Penetration Testing

Start with initial reconnaissance
- Use Claude to help formulate a plan for approaching the HTB machine
- Select the "initial_recon" prompt from the MCP server
Discover and enumerate services
- Use nmap to scan for open ports and services
- Use Claude to help interpret the results
Explore identified services
- For web servers, use gobuster, dirb, nikto, and wpscan
- For database servers, use sqlmap
- For Windows/Samba servers, use enum4linux
Exploit vulnerabilities
- Based on Claude's recommendations, use appropriate tools to exploit discovered vulnerabilities
- Use metasploit when applicable
Post-exploitation
- Privilege escalation
- Data exfiltration
- Establish persistence (for training purposes only)

Troubleshooting

Debugging Features

If you're experiencing issues, run the servers in debug mode:

./run.py --debug

This enables:

Detailed Logging: All operations are logged to debug.log
Debug Endpoints:
- http://localhost:8080/debug/status - MCP server status
- http://localhost:5000/debug/status - API server status
- http://localhost:8080/debug/config - MCP server configuration
- http://localhost:5000/debug/tool-test - Test if tools are working
- http://localhost:8080/debug/test-api - Test MCP-API connection
- http://localhost:8080/debug/history - Request history (last 100 requests)
Health Checks:
- http://localhost:8080/health - MCP server health check that includes API server status
- http://localhost:5000/health - API server health check that includes tool availability
Command Debugging (use with caution):
- http://localhost:5000/debug/command - Safe command execution for troubleshooting

All endpoints can be accessed via your browser or using tools like curl.

Dependency Conflicts

If you're experiencing conflicts with system packages:

Make sure you're using the virtual environment
Never install packages with --break-system-packages
If you need to recreate the virtual environment: rm -rf venv && ./setup.sh

Server Issues

If a tool is not working, ensure it's installed and accessible in your PATH
Check the logs of both servers for error messages
Verify that Claude for Desktop is properly configured to use the MCP server

Security Considerations

This setup should be used in a controlled environment (like HTB) for legal penetration testing only
Never use these tools against systems without explicit permission
The API server executes commands directly on your system - use with caution
Consider running in a VM or container for additional isolation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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