# Kali Linux MCP Server & Client

A high-performance Model Context Protocol (MCP) Server and Client ecosystem running **natively on Kali Linux**, providing AI assistants (VSCode, Claude Desktop, Antigravity IDE) full, structured access to all 600+ installed security, penetration testing, and forensic tools.

---

## Features

- **600+ Kali Tools Available**: Execute any binary tool in the full Kali suite natively (Nmap, Metasploit, Sqlmap, Gobuster, Nikto, John the Ripper, Hydra, Wireshark, Searchsploit, Ghidra, etc.).
- **VirtualBox / Remote VM Support**:
  - Run `server.py` inside a VirtualBox Kali VM (listening on host-only or bridged network adapter).
  - Run `client.py` on your Windows Host inside `mcp.json`. It bridges local Stdio to remote Kali SSE HTTP seamlessly!
- **Dual Transport Architecture**:
  - **Stdio Mode**: For single-machine local setup.
  - **SSE HTTP Mode**: For cross-machine or VirtualBox / VMware / WSL2 setups.
- **Dynamic Tool Discovery & Manpages**: Automatically search installed tools by category and query manpages (`man <tool>`) or `--help` documentation on the fly.
- **Structured Wrappers & Workspace Management**: Includes high-level JSON wrappers for key tools (`nmap`, `sqlmap`, `gobuster`, `searchsploit`) and local artifact/file management.

---

## Installation

### On Kali Linux (Server)

```bash
git clone https://github.com/your-repo/kali-mcp.git
cd kali-mcp
python3 -m pip install -r requirements.txt
python3 -m pip install -e .
```

### On Windows Host (Client)

```cmd
git clone https://github.com/your-repo/kali-mcp.git
cd kali-mcp
pip install -r requirements.txt
pip install -e .
```

---

## Usage Scenarios

### Scenario 1: VirtualBox / Remote Kali Setup (Recommended for Windows Host + Kali VM)

1. **On VirtualBox Kali VM**:
   Check your Kali VM host-only or bridged IP address (`ip a`, e.g. `192.168.56.101`), then run the server:
   ```bash
   python3 server.py --host 0.0.0.0 --port 8000
   # Or using the installed CLI:
   kali-mcp-server --host 0.0.0.0 --port 8000
   ```

2. **In VSCode / Claude Desktop / Antigravity IDE on Windows Host**:
   Configure your `mcp.json` file:
   ```json
   {
     "mcpServers": {
       "kali-linux": {
         "command": "python",
         "args": [
           "C:/path/to/kali-mcp-tool/client.py",
           "--server", "192.168.56.101",
           "--port", "8000"
         ]
       }
     }
   }
   ```
   *Alternatively, if installed via `pip install -e .`, you can use the installed CLI command directly:*
   ```json
   {
     "mcpServers": {
       "kali-linux": {
         "command": "kali-mcp-client",
         "args": [
           "--server", "192.168.56.101",
           "--port", "8000"
         ]
       }
     }
   }
   ```
   The client will bridge Stdio from your IDE directly to your VirtualBox Kali VM over SSE!

3. **Interactive Terminal Client (Optional)**:
   You can test tools directly from a terminal prompt:
   ```cmd
   python client.py --server 192.168.56.101 --port 8000 --interactive
   # Or:
   kali-mcp-client --server 192.168.56.101 --port 8000 --interactive
   ```

---

### Scenario 2: Local Single-Environment Setup (Running inside Kali directly)

If your IDE is running directly on Kali Linux:
```json
{
  "mcpServers": {
    "kali-linux": {
      "command": "python3",
      "args": [
        "/path/to/kali-mcp-tool/server.py"
      ]
    }
  }
}
```
*Or using the installed command:*
```json
{
  "mcpServers": {
    "kali-linux": {
      "command": "kali-mcp-server"
    }
  }
}
```

---

## Available MCP Tools

| Tool | Description |
|---|---|
| `kali_execute_command` | Execute any arbitrary shell command natively on Kali with timeout control. |
| `kali_search_tools` | Search installed Kali tools by name, keyword, or category. |
| `kali_get_tool_help` | Dynamically fetch manpages (`man`) or `--help` documentation for any tool. |
| `kali_run_nmap` | High-level Nmap port/service scanner wrapper. |
| `kali_run_sqlmap` | Automatic SQL injection scan wrapper. |
| `kali_run_gobuster` | Web directory & DNS brute-forcing wrapper. |
| `kali_run_searchsploit` | Search ExploitDB offline exploit database. |
| `kali_manage_workspace` | Read, write, list, or delete scan logs & target lists in workspace directory. |

---

## Security & Ethics Warning

> [!WARNING]
> Penetration testing tools should **only** be executed against targets you own or have explicit, documented permission to test. Always operate responsibly and in accordance with applicable laws.