MCP Kali

Give your AI agent a full Kali Linux arsenal, not just a handful of wrapped CLI tools.

A Model Context Protocol (MCP) server that runs inside a Kali Linux Docker container, giving AI agents full access to offensive security tooling through a standardized interface.

Built for real-world offensive security and CTF work, battle-tested through hundreds of Hack The Box machines, contributing to a Top #100 global ranking on the platform.

---

✨ Features at a Glance

Feature	What It Means
Unrestricted Command Execution	Run any command — not limited to a predefined list of tools
Interactive PTY Sessions	SSH, telnet, netcat, SQL shells, reverse shells — full back-and-forth interaction
Background Tasks	Fire off long-running scans without blocking the conversation
HTTP Intercepting Proxy	Capture, inspect, export, and replay HTTP traffic (built on mitmproxy)
Dynamic Tool Discovery	Find, install, and register new tools at runtime — zero restarts
OpenTelemetry (OTLP) Ready	Trace and capture every tool execution for full observability
Batteries Included	Ships with 1000+ security tools pre-installed in a Kali container

---

🤔 Why MCP Kali?

MCP Kali isn't a wrapper around security tools — it's a full Kali Linux environment exposed to your AI agent through MCP primitives. Instead of one MCP function per tool, it provides building blocks that let the agent operate freely:

• Execute any command available in Kali, not just a predefined list
• Open interactive sessions for services that need back-and-forth (SSH, SQL shells, reverse shells)
• Run scans in the background while continuing other work
• Intercept and replay HTTP traffic for web testing
• Install new tools on the fly without restarting the server

The agent decides how to combine them, just like working in a real terminal.

---

🚀 Quick Start

1. Build the Docker image

docker build -t mcp-kali .

2. Run the container

docker run -d --name mcp-kali --privileged mcp-kali

3. Configure Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "kali": {
      "type": "stdio",
      "command": "docker",
      "args": ["exec", "-i", "mcp-kali", "python3", "/opt/mcp_server.py"]
    }
  }
}

---

📖 Documentation

• Tools Reference — full list of MCP tools, sessions, background tasks, proxy, and meta-tools
• Architecture & Container — internals, design decisions, pre-installed packages, and OTLP tracing

---

🧪 Running Tests

Tests run inside Docker to match the production environment:

docker build -t mcp-kali .
docker run --rm -v $(pwd):/mcp-kali -w /mcp-kali mcp-kali \
  bash -c "pip3 install --quiet --break-system-packages pytest && python3 -m pytest tests/ -v"

140 tests covering the tool registry, JSON-RPC protocol, session management, concurrent execution, meta-tools, resources, and dynamic registration.

---

⚠️ Disclaimer

This project is shared for educational and research purposes only. It provides unrestricted command execution inside a Kali Linux container — use it responsibly and at your own risk. The authors assume no liability for misuse. Always ensure you have proper authorization before testing any target.

---

📄 License

MIT