HackBridge

HackBridge is a lightweight MCP (Model Context Protocol) bridge that connects AI clients (e.g., Claude Desktop, 5ire) to a Linux terminal API server — enabling AI-assisted penetration testing, CTF challenge solving, and automated recon/exploitation in real time.

Run terminal commands like nmap, sqlmap, or any other tool. Interact with web applications using curl, wget, gobuster. Let the AI drive your offensive security workflow — from enumeration to exploitation.

🔍 Use Case

HackBridge enables AI-driven offensive security by:

• Connecting MCP-compatible AI clients (OpenAI, Claude, DeepSeek, Gemini, etc.) to a Linux terminal.
• Exposing a controlled API to execute commands on your Linux machine.
• Letting AI suggest, run, and analyze terminal commands to solve CTF challenges or automate recon/exploitation tasks.
• Allowing MCP apps to send structured requests (e.g., nmap, ffuf, curl) and receive parsed outputs.

---

🚀 Features

• 🧠 AI Integration via MCP — Connect your Linux machine to any MCP-compatible client like Claude Desktop or 5ire.
• 🖥️ Command Execution API — Controlled API to execute terminal commands on your Linux machine.
• 🛠️ Built-in Tool Support — Pre-configured endpoints for Nmap, Gobuster, Dirb, SQLMap, Hydra, and WPScan.
• 🕸️ Web Challenge Support — AI can interact with websites and APIs, capture flags via curl and any other tool.
• ⏱️ Configurable Timeouts — Per-tool timeout support to handle long-running scans without interruption.
• 🔐 Built for Offensive Security — Ideal for red teamers, bug bounty hunters, and CTF players automating common tasks.
• 🔄 Arbitrary Command Execution — Execute any terminal command beyond the built-in tools for maximum flexibility.

---

📁 Project Structure

MCP-Kali-Server/
├── kali_server.py          # Flask API server (runs on Linux/Kali)
├── mcp_server.py           # MCP client bridge (connects AI to API server)
├── mcp-kali-server.json    # Example MCP client configuration
├── requirements.txt        # Python dependencies
└── README.md               # This file

---

🛠️ Installation & Setup

Prerequisites

• Python 3.8+
• pip (Python package manager)
• The following Python packages (installed via requirements.txt):
  • Flask>=3.0.0
  • requests>=2.31.0
  • mcp>=1.0.0

1. On Your Linux Machine (API Server)

Install HackBridge via apt:

sudo apt install hackbridge

Or install manually:

git clone <your-repo-url>
cd MCP-Kali-Server
pip install -r requirements.txt
python3 kali_server.py

Command Line Options:

• --ip <address> — IP to bind the server to (default: 127.0.0.1 for localhost only)
  • 127.0.0.1 — Local connections only (secure, recommended)
  • 0.0.0.0 — Allow connections from any interface (⚠️ very dangerous; use with caution)
  • Specific IP — Bind to a particular network interface
• --port <port> — Port number (default: 5000)
• --debug — Enable debug mode for verbose logging

Examples:

# Run on localhost only (secure, default)
python3 kali_server.py

# Run on all interfaces (less secure, useful for remote access)
python3 kali_server.py --ip 0.0.0.0

# Run on a specific IP and custom port
python3 kali_server.py --ip 192.168.1.100 --port 8080

# Run with debug mode
python3 kali_server.py --debug

2. On Your MCP Client Machine (Can Be Local or Remote)

git clone <your-repo-url>
cd MCP-Kali-Server
pip install -r requirements.txt

MCP Client Command Line Options:

• --server <url> — Kali API server URL (default: http://localhost:5000)
• --timeout <seconds> — Request timeout in seconds (default: 600)
• --debug — Enable debug logging

If running the client and server on the same machine:

python3 mcp_server.py --server http://127.0.0.1:5000

If on separate machines, create an SSH tunnel to your Linux machine, then launch the client:

ssh -L 5000:localhost:5000 user@LINUX_IP
python3 mcp_server.py --server http://127.0.0.1:5000

Note: If you're openly hosting the API server on your network (kali_server.py --ip 0.0.0.0), you don't need the SSH tunnel — but ⚠️ this is highly discouraged for security reasons.

python3 mcp_server.py --server http://LINUX_IP:5000

---

⚙️ MCP Client Configuration

Claude Desktop

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

{
    "mcpServers": {
        "hackbridge": {
            "command": "python3",
            "args": [
                "/absolute/path/to/mcp_server.py",
                "--server",
                "http://LINUX_IP:5000/"
            ],
            "timeout": 600
        }
    }
}

5ire Desktop Application

Simply add an MCP server with the command:

python3 /absolute/path/to/mcp_server.py --server http://LINUX_IP:5000

5ire will automatically generate the needed configuration files.

---

🧰 Supported Tools

Tool	MCP Function	Description
Nmap	nmap_scan	Network scanning & version detection
Gobuster	gobuster_scan	Directory, DNS, and vhost brute-forcing
Dirb	dirb_scan	Web content scanning
SQLMap	sqlmap_scan	SQL injection testing
Hydra	hydra_attack	Password brute-forcing
WPScan	wpscan_analyze	WordPress vulnerability scanning
Any command	execute_command	Execute any arbitrary terminal command

---

🔌 API Endpoints

The Flask API server (kali_server.py) exposes the following endpoints:

Method	Endpoint	Description
POST	/api/command	Execute any arbitrary command
POST	/api/tools/nmap	Run an Nmap scan
POST	/api/tools/gobuster	Run a Gobuster scan
POST	/api/tools/dirb	Run a Dirb scan
POST	/api/tools/sqlmap	Run a SQLMap scan
POST	/api/tools/hydra	Run a Hydra attack
POST	/api/tools/wpscan	Run a WPScan scan
GET	/health	Server health check

---

🔮 Other Possibilities

Since the AI model can now execute commands on the terminal, the possibilities go beyond just pentesting:

• Memory Forensics with Volatility — Automate memory analysis: process enumeration, DLL injection checks, registry extraction from memory dumps.
• Disk Forensics with SleuthKit — Automate disk image analysis, timeline generation, file carving, and hash comparisons.
• OSINT & Recon — Automate recon workflows using tools like theHarvester, amass, subfinder, etc.
• Log Analysis — Parse and analyze security logs, access logs, or system logs.