# wh0am123/mcp-kali-server architecture

> Architecture diagram of the GitHub repository wh0am123/mcp-kali-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wh0am123/mcp-kali-server
- Repository: https://github.com/wh0am123/mcp-kali-server

## Overview

1. **Repository shape**
   - This is a very small Python project with two runtime entrypoints: `server.py` and `client.py`.
   - The rest is support files: `requirements.txt` for dependencies, `mcp-kali-server.json` for MCP desktop configuration, and the README/docs.

2. **Primary architectural split**
   - The repo is divided into two sides:
     - **Server side** on the Kali machine: exposes command-execution capability.
     - **Client side** on the MCP consumer machine: connects an MCP-capable desktop/app to the server.
   - This is not a monolith; it is a bridge between an AI/MCP client and a remote shell-like service.

3. **Server subsystem**
   - `server.py` is the security-sensitive core.
   - It binds to an IP/port, accepts requests, and executes terminal commands on the host OS.
   - The README indicates it is intended to run on Kali Linux and can invoke common offensive-security tools plus arbitrary shell commands.

4. **Client subsystem**
   - `client.py` is the MCP-facing adapter.
   - Its job is to connect an MCP application to the server endpoint over HTTP, translating MCP tool calls into server requests and returning outputs back to the model/client.
   - In the architecture diagram, this is the boundary between the AI host application and the Kali execution environment.

5. **External client applications**
   - The repo is designed to be driven by MCP-aware desktop apps such as Claude Desktop or 5ire.
   - Those apps do not directly execute commands; they consume the MCP client, which in turn talks to the Kali server.
   - This makes the MCP client the integration point for different AI endpoints.

6. **Command-execution data flow**
   - Typical flow: AI model or MCP app → `client.py` → HTTP request to `server.py` → shell command/tool execution on Kali → command output returned back through the same path.
   - The outputs are described as structured enough for automation, so the interface is more than raw terminal streaming; it is intended for tool-oriented responses.

7. **Network and deployment boundaries**
   - By default the server binds to `127.0.0.1`, which keeps it local to the machine.
   - For remote use, the README recommends an SSH tunnel rather than exposing the server broadly.
   - `0.0.0.0` binding is explicitly supported but called out as dangerous; this is the main security boundary in the system.

8. **Tooling surface**
   - The server is meant to orchestrate installed Kali tooling such as `nmap`, `gobuster`, `sqlmap`, `nikto`, `hydra`, `john`, `metasploit`, and others.
   - Architecturally, these tools are not separate services in the repo; they are external host-level executables invoked by the server process.

9. **Configuration and distribution**
   - `mcp-kali-server.json` exists to help wire the client into Claude Desktop-style MCP configuration.
   - `requirements.txt` likely captures the Python MCP/networking dependencies needed by both entrypoints.
   - The repo appears designed for both package-based install and direct-from-source execution.

10. **State and persistence**
   - There is no evidence of a database, message queue, cache, or job runner in the repo.
   - That suggests a stateless request/response architecture: each command is executed on demand and the result is returned immediately.

11. **Security model**
   - The biggest architectural concern is trust and isolation, because the system intentionally exposes shell execution.
   - The server should be treated as a privileged execution boundary on Kali, and the client as a transport/integration layer rather than a security control.
   - For a diagram, this is the key “dangerous boundary” to highlight.

12. **How to diagram it**
   - Draw three layers:
     - **MCP desktop/AI app**
     - **`client.py` bridge**
     - **`server.py` on Kali with shell/tool execution**
   - Then show an optional **SSH tunnel** between client and server when remote.
   - External Kali tools belong on the server side, not as separate repo components.

Main entry points: [`server.py`](https://github.com/wh0am123/mcp-kali-server/blob/main/server.py) (server.py), [`client.py`](https://github.com/wh0am123/mcp-kali-server/blob/main/client.py) (client.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["MCP Desktop Layer"]
  node_n1["MCP Apps<br/>mcp client"]
end

subgraph group_g2["Bridge Layer"]
  node_n2["client.py<br/>mcp bridge<br/>[client.py]"]
  node_n3(("SSH Tunnel<br/>transport"))
  node_n7["Config Files<br/>repo config"]
end

subgraph group_g3["Kali Execution Layer"]
  node_n4["server.py<br/>command server<br/>[server.py]"]
  node_n5{{"Shell Exec<br/>execution boundary"}}
  node_n6["Kali Tools<br/>host utilities"]
end

node_n1 -->|"tool calls"| node_n2
node_n2 -.->|"optional remote path"| node_n3
node_n3 -->|"HTTP requests"| node_n4
node_n2 -->|"direct HTTP"| node_n4
node_n4 -->|"execute"| node_n5
node_n5 -->|"invoke tools"| node_n6
node_n4 -->|"results back"| node_n1
node_n7 -.->|"configure client"| node_n2
node_n7 -.->|"runtime deps"| node_n4

click node_n2 "https://github.com/wh0am123/mcp-kali-server/blob/main/client.py"
click node_n4 "https://github.com/wh0am123/mcp-kali-server/blob/main/server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1 toneBlue
class node_n2,node_n3,node_n7 toneAmber
class node_n4,node_n5,node_n6 toneMint
```

## Components

### MCP Desktop Layer

AI/MCP consumer applications that initiate tool calls

- **MCP Apps**: mcp client · Claude Desktop-style or other MCP-aware desktop apps that issue tool requests

### Bridge Layer

Local MCP adapter and optional remote transport

- [client.py](https://github.com/wh0am123/mcp-kali-server/blob/main/client.py): mcp bridge · MCP-facing adapter that translates tool calls into HTTP requests to the server · `client.py`
- **SSH Tunnel**: transport · Recommended secure path for reaching a remote server without exposing it broadly
- **Config Files**: repo config · mcp-kali-server.json and requirements.txt used to wire the client and runtime dependencies

### Kali Execution Layer

Privileged command execution on the Kali host

- [server.py](https://github.com/wh0am123/mcp-kali-server/blob/main/server.py): command server · HTTP service that accepts requests and executes host commands · `server.py`
- **Shell Exec**: execution boundary · Privileged terminal command execution on the Kali host
- **Kali Tools**: host utilities · External tools invoked by the server such as nmap, gobuster, sqlmap, nikto, hydra, john, and metasploit

## Connections

- MCP Apps → client.py: tool calls · MCP app sends requests to the local bridge
- client.py → SSH Tunnel: optional remote path · Traffic can be tunneled when the server is on another machine
- SSH Tunnel → server.py: HTTP requests · Tunnel carries client traffic to the server endpoint
- client.py → server.py: direct HTTP · Local or directly reachable server access
- server.py → Shell Exec: execute · Server turns requests into host command execution
- Shell Exec → Kali Tools: invoke tools · Commands may run installed Kali utilities or arbitrary shell commands
- server.py → MCP Apps: results back · Outputs return through the bridge to the MCP app
- Config Files → client.py: configure client · Desktop/client wiring and dependency setup
- Config Files → server.py: runtime deps · Python dependencies support the server runtime