How wh0am123/mcp-kali-server works
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 server.py · client.py client.py
Components 7
MCP Desktop Layer
AI/MCP consumer applications that initiate tool calls
- MCP Apps · Claude Desktop-style or other MCP-aware desktop apps that issue tool requests
Bridge Layer
Local MCP adapter and optional remote transport
- client.py · MCP-facing adapter that translates tool calls into HTTP requests to the server
client.py - SSH Tunnel · Recommended secure path for reaching a remote server without exposing it broadly
- Config Files · 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 · HTTP service that accepts requests and executes host commands
server.py - Shell Exec · Privileged terminal command execution on the Kali host
- Kali Tools · External tools invoked by the server such as nmap, gobuster, sqlmap, nikto, hydra, john, and metasploit
Connections 9
- 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