HackBridge MCP Server

🌉 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, nxc, 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 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
        }
    }
}

[5ir