Kali MCP Server

A Model Context Protocol (MCP) server that exposes Kali Linux tools to AI agents. This allows LLMs to discover and execute security testing tools like nmap, sqlmap, hydra, metasploit, etc.

This server runs inside a Kali Linux Docker container and provides MCP tools to:

• List all available Kali tools
• Check if a specific tool is available
• Execute Kali tools with arguments
• Monitor server health

┌─────────────┐     ┌──────────────────────────┐
│   MCP Host  │────▶│  Kali MCP Server         │
│ (e.g., LLM) │     │  FastMCP + Docker        │
│             │◀────│  (stdio transport)       │
└─────────────┘     └──────────────────────────┐
                    │  Kali Linux Container    │
                    │  - /usr/bin tools        │
                    │  - /usr/sbin tools       │
                    └────────────────────────────┘

• Docker installed on your system
• Python 3.10+ (for local development)

docker build -t kali-mcp-server:latest .

If your Docker environment sits behind TLS inspection or a corporate proxy, inject the trusted root CA during build:

docker build \
  --build-arg KALI_REPO_URL=https://http.kali.org/kali \
  --build-arg CUSTOM_CA_PEM="$(cat company-root-ca.crt)" \
  -t kali-mcp-server:latest .

Notes:

• company-root-ca.crt should be a PEM-encoded root certificate trusted by your network.
• The Dockerfile defaults to Kali's official http://http.kali.org/kali source. If you switch to HTTPS, the Dockerfile installs this certificate before apt-get update so Kali package downloads can validate TLS correctly.
• If your shell has trouble with multiline PEM build args, prefer the prebuilt image workflow below.

The Docker image is built from kalilinux/kali-rolling and includes:

• Python 3 with FastMCP SDK
• Kali Linux toolset (all tools from /usr/bin, /usr/sbin)
• MCP server configuration

If your environment cannot build from Kali package repositories, you can provide the image ahead of time and skip the local build step.

docker load < kali-mcp-server.tar

docker pull <your-registry>/kali-mcp-server:latest
docker tag <your-registry>/kali-mcp-server:latest kali-mcp-server:latest

docker image inspect kali-mcp-server:latest

The MCP client configuration in this repository expects the local image name kali-mcp-server:latest.

The MCP server connects directly through Docker using the mcp.json configuration:

# Ensure Docker is running
docker ps

# The server starts automatically when your MCP client connects

# Start container interactively
docker run -it --name kali-mcp kali-mcp-server:latest

# Run commands inside the container
docker exec -it kali-mcp python3 /app/server.py

The mcp.json file contains the MCP server configuration:

{
  "mcpServers": {
    "kali-linux-tools": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--name",
        "kali-mcp-${SESSION_ID}",
        "kali-mcp-server:latest"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

This configuration:

• Uses Docker as the command to run
• Runs a fresh container for each session (--rm)
• Uses stdio transport for MCP protocol
• Names containers uniquely per session

This repository includes add.sh, a helper script that installs the Kali MCP server entry into supported MCP client configs.

• Claude Desktop
• Claude Code
• Cursor
• Windsurf
• VS Code / GitHub Copilot
• Continue
• Cline
• Roo Code
• OpenCode
• Zed
• Codex
• Gemini CLI

# Show help
./add.sh --help

# Add to a single client
./add.sh --claude-desktop
./add.sh --opencode

# Add to multiple clients at once
./add.sh --claude-code --cursor --vscode

# Add to every supported target
./add.sh --all

• Uses the local docker-wrapper.sh path from this repository
• Adds or updates the kali-linux-tools MCP entry
• Creates missing config files and parent directories when needed
• Preserves unrelated config entries in existing files

• Project-level targets write into this repository.
• Global targets write into your home directory config locations.
• The script now handles macOS, Linux, and Windows-style config paths for supported global targets.
• On Windows, run the script from Git Bash, MSYS2, or Cygwin so bash and the wrapper-based command remain valid.
• After updating a client config, restart that client so it reloads MCP servers.

Once the Docker image is built, an MCP client can launch this server on demand and call its tools.

This repository includes deploy_kali_mcp.sh to automate common local deployment tasks:

1. Build the Docker image (kali-mcp-server:latest by default)
2. Install/update the systemd service using install_systemd_service.sh
3. Install/update the Claude agent file at ~/.claude/agents/kali-operator.md

# Show help
./deploy_kali_mcp.sh --help

# Preview actions without making changes
./deploy_kali_mcp.sh --dry-run

# Run full deployment
./deploy_kali_mcp.sh

Optional overrides:

# Use a custom Docker tag
./deploy_kali_mcp.sh --image-tag kali-mcp-server:stable

# Install agent file to a custom Claude agents directory
./deploy_kali_mcp.sh --claude-agent-dir /path/to/agents

Notes:

• install_systemd_service.sh install may prompt for sudo/root privileges.
• The script is intended for Linux hosts that use systemd.

# 1. Build the image, or load/pull a prebuilt one
docker build -t kali-mcp-server:latest .

# If needed, force HTTPS mirror and inject a trusted corporate/proxy root CA
# docker build --build-arg KALI_REPO_URL=https://http.kali.org/kali --build-arg CUSTOM_CA_PEM="$(cat company-root-ca.crt)" -t kali-mcp-server:latest .

# Alternative: load or pull a prebuilt image
# docker load < kali-mcp-server.tar
# docker pull <your-registry>/kali-mcp-server:latest
# docker tag <your-registry>/kali-mcp-server:latest kali-mcp-server:latest

# 1b. Verify the image exists locally
docker image inspect kali-mcp-server:latest

# 2. Install the MCP entry into one or more clients
./add.sh --claude-desktop
# or
./add.sh --claude-code --cursor --vscode

# 3. Restart the client you updated

1. Your MCP client loads the kali-linux-tools server entry.
2. When the client connects, it starts the Docker-backed server.
3. The client discovers the available MCP tools.
4. You ask the client to inspect tools or run a Kali command.
5. The server returns structured results over MCP.

After restarting your MCP client, verify the server is available by asking it to:

• list available tools from kali-linux-tools
• run health_check
• run server_info

If the client is connected correctly, it should show the server tools and return a healthy status.

Use prompts like these in your MCP-enabled client:

• List the first 20 Kali tools exposed by kali-linux-tools.
• Check whether sqlmap is installed.
• Run nmap --version using the kali-linux-tools MCP server.
• Run health_check on the kali-linux-tools server.
• Show server_info for the kali-linux-tools MCP server.

• Start with read-only or version-check commands such as --help or --version.
• Prefer targeted commands over broad scans until you confirm the client-server setup works.
• Treat execute_tool as direct command execution inside the Kali container.
• Review generated arguments in your client before approving tool execution.
• Use this server only in environments where running security tools is appropriate.
• add.sh installs MCP client config only; it does not build, pull, or publish Docker images.
• In restricted environments, using a prebuilt kali-mcp-server:latest image may be more reliable than building locally.

The server exposes the following tools through MCP:

List all available Kali tools.

Arguments:

• limit (optional): Maximum number of tools to return

Check if a specific Kali tool is available.

Arguments:

• tool_name (required): Name of the tool to check

Execute a Kali tool with specified arguments.

Arguments:

• tool (required): Name of the Kali tool to execute
• arguments (optional, default: []): List of command line arguments for the tool
• timeout (optional, default: 60): Timeout in seconds for command execution

Check server health status.

Arguments: None

Get server information and available endpoints.

Arguments: None

# Install dependencies
pip install "mcp[cli]" uvicorn

# Run server
python3 server.py [--transport stdio|streamable-http]

Server will start with stdio transport (default) or HTTP on port 3001.

• server.py - FastMCP server implementation
• mcp.json - MCP server configuration for Docker
• Dockerfile - Docker image definition
• README.md - This documentation

⚠️ IMPORTANT: This server executes system commands and should be used with caution:

• ⚠️ No authentication - This is a local development tool only
• ⚠️ Direct command execution - Any Kali tool can be run with any arguments
• ⚠️ No input validation - Arguments are passed directly to system commands

If deploying in a production environment:

1. Add authentication (API keys, OAuth, etc.)
2. Implement input validation and sanitization
3. Add rate limiting
4. Restrict which tools can be executed
5. Run in a restricted Docker network
6. Enable logging and monitoring

# Check if Docker is running
docker ps

# Check logs
docker logs kali-mcp-${SESSION_ID}

# Ensure image exists
docker images | grep kali-mcp-server

# Verify container is running Kali Linux
docker exec -it kali-mcp-${SESSION_ID} cat /etc/os-release

# Check tool directory
docker exec kali-mcp-${SESSION_ID} ls /usr/bin | head -20

# Verify container is running
docker ps | grep kali-mcp

# Check container ports (if using HTTP transport)
docker port kali-mcp-${SESSION_ID}

Ensure Docker is installed and accessible in your PATH:

docker --version

This is a work in progress for internal/testing use only.