Claude Kali MCP Commander

Claude Kali MCP Integration

A clean, minimal implementation of Kali Linux MCP (Model Context Protocol) integration for Claude Desktop, providing secure access to Kali Linux tools through Claude's interface. This project enables seamless execution of security tools and commands within an isolated Docker container.

Features

🐳 Docker-based - Containerized environment for consistent execution
🔒 Isolated Environment - Kali Linux tools in a secure sandbox
🔄 Automatic Health Checks - Ensures service reliability and availability
📡 MCP Server - Standard protocol integration with Claude Desktop
🚀 Quick Setup - Get started with minimal configuration
🔧 Configurable - Customizable ports and settings
🔍 Security-First - Isolated execution environment for security tools
📊 Monitoring - Built-in health checks and status endpoints

Prerequisites

Docker (v20.10.0+)
Docker Compose (v2.0.0+)
Git (for cloning the repository)
Node.js (v16+ for development and testing)

Networking Note

By default, the provided docker-compose.yml and docker-compose.full.yml files use host networking (network_mode: host). This gives the containers full access to the host network, which is required for some advanced networking tools and scenarios.

Security Note:

Host networking provides less isolation between your host and the containers. All network interfaces and ports are shared.
If you prefer more isolation, you can switch to Docker's default bridge network by removing the network_mode: host lines and adding a ports: mapping (e.g., 8081:8080) to the relevant service(s). See the commented examples in the compose files and documentation below for details.

Quick Start

Clone the repository:
git clone https://github.com/house-of-stark/Claude-Kali-MCP-Commander cd Claude-Kali-MCP-Commander

🛠️ Build & Run Instructions

Note: sudo is enabled inside the Kali container for tools like nmap and others that require elevated privileges. If you want to restrict the use of sudo, edit the blockedCommands list in config.json.

Windows (PowerShell)

Note: If you see a script signing or execution policy error, run the script with ExecutionPolicy Bypass:

Minimal build (recommended):
powershell -ExecutionPolicy Bypass -File .\build.ps1 docker-compose up -d
Full Kali tools build:
powershell -ExecutionPolicy Bypass -File .\build.ps1 -Profile full docker-compose -f docker-compose.full.yml up -d

Linux / macOS (Bash)

Minimal build (recommended):
./build.sh minimal docker-compose up -d
Full Kali tools build:
./build.sh full docker-compose -f docker-compose.full.yml up -d

Start & Monitor Services

Quick start script (Linux/macOS):
chmod +x start.sh ./start.sh
This builds and starts the containers, waits for readiness, and shows status.
Check health endpoint:
curl http://localhost:8080/health
Should return: {"status":"ok"}
View running containers:
docker ps --filter "name=kali-mcp-commander"

Configure Claude Desktop

Set MCP Server URL to: http://localhost:8080
(Optional) Set Project Path to your local repo directory

Choose your build profile:
- Minimal (Default): Small image with just the MCP server (recommended for most users)
  ./build.sh minimal docker-compose up -d
- Full: Complete Kali Linux with all tools (very large image)
  ./build.sh full docker-compose -f docker-compose.full.yml up -d
The minimal build is much faster and smaller, while the full build includes all Kali Linux tools but requires significant disk space.
Verify the installation:
curl http://localhost:8081/health
Should return: {"status":"ok"}
Configure Claude Desktop:
- Open Claude Desktop settings
- Set MCP Server URL to: http://localhost:8081
- Set Project Path to the full path of this repository (e.g., /path/to/Claude-Kali-MCP-Commander)
- Restart Claude Desktop

Project Structure

.
├── .gitignore           # Git ignore file
├── CONTRIBUTING.md      # Contribution guidelines
├── Dockerfile           # Kali Linux container setup with MCP server
├── LICENSE              # MIT License
├── README.md            # This file
├── config/              # Configuration files
│   └── claude_desktop_config.json  # Claude Desktop configuration
├── docker-compose.yml   # Service definitions and orchestration
├── health-server.js     # Health check server implementation
├── package.json         # Node.js dependencies
└── start.sh             # Helper script to start services

Testing the Integration

After starting the services, you can test the MCP integration:

Basic Health Check: (If using bridging to Docker)
curl http://localhost:8081/health
Should return: {"status":"ok"}
Verify Container Status:
docker ps --filter "name=kali-mcp-commander-minimal"
Should show the container as "healthy"
View Container Logs:
docker logs kali-mcp-commander
Check for any error messages or warnings

Configuration

Claude Desktop Configuration

To use this MCP server with Claude Desktop, you'll need to configure the following in your Claude Desktop settings:

Kali Linux MCP (Required): Runs commands inside the Docker container with Kali Linux tools
Host OS Commander (Optional): Can be used to run commands directly on the host OS where Claude Desktop is installed. You can remove this section if you only need the Kali Linux environment.

Example single MCP Server claude_desktop_config.json:

{
  "mcpServers": {
    "kali-mcp": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "kali-mcp-commander-minimal",
        "npx",
        "@wonderwhy-er/desktop-commander"
      ],
      "name": "Kali Linux MCP",
      "description": "Access Kali Linux security tools via MCP"
    }
  },
  "defaultMcpServerId": "kali-mcp"
}

Example MCP Commander Desktop OS and Kali MCP Server claude_desktop_config.json:

{
  "mcpServers": {
    "kali-mcp": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "kali-mcp-commander-minimal",
        "npx",
        "@wonderwhy-er/desktop-commander"
      ],
      "name": "Kali Linux MCP",
      "description": "Access Kali Linux security tools via MCP"
    },
    "desktop-commander": {
      "command": "npx",
      "args": [
        "@wonderwhy-er/desktop-commander@latest"
      ],
      "name": "Host OS Commander",
      "description": "Access commands on the host OS where Claude Desktop is installed"
    }
  },
  "defaultMcpServerId": "kali-mcp"
}

Environment Variables

You can customize the following environment variables in the docker-compose.yml file:

MCP_SERVER_PORT: Port for the MCP server (default: 8080)
NODE_ENV: Environment mode (development/production)
LOG_LEVEL: Logging verbosity (debug, info, warn, error)

Port Configuration (if not using host networking)

To change the default ports, modify the ports section in docker-compose.yml:

ports:
  - "8081:8080"  # HostPort:ContainerPort

Troubleshooting

Common Issues

Port Conflicts
- Symptom: Container fails to start with port binding errors
- Solution: Change the host port in docker-compose.yml
Container Health Check Fails
- Symptom: Container restarts continuously
- Solution: Check logs with docker logs kali-mcp-commander-minimal
MCP Server Not Responding
- Symptom: Claude Desktop can't connect to the MCP server
- Solution:
  - Verify the server is running: curl http://localhost:8081/health
  - Check Docker network settings
  - Ensure no firewall is blocking port 8081

Debugging

For detailed debugging, you can modify the docker-compose.yml to include additional logging:

environment:
  - NODE_ENV=development
  - DEBUG=*

Security Considerations

The container runs with minimal privileges
Network access is restricted to localhost by default
Regular security updates are recommended for the base Kali Linux image
Review the Dockerfile for any custom configurations

Performance

The container is optimized for minimal resource usage
Health checks ensure service availability
Resource limits can be configured in docker-compose.yml

Contributing

Contributions are welcome! Please read our Contributing Guidelines for details on how to contribute to this project.

When contributing, please:

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a new Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Original work by Eduard Ruzga (2024)

Support

For support, please open an issue on GitHub.

You must be authenticated.

security – no known vulnerabilities

license - not found

quality - confirmed to work

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

View all tools

An MCP server that provides secure access to Kali Linux cybersecurity tools through Claude's interface, enabling users to run Kali Linux commands directly from Claude Desktop.

Related MCP Servers

mcp-server-commands
g0t4
A
security
A
license
A
quality
An MCP server to run commands.
Last updated -
2
265
150
TypeScript
MIT License
mcp-wsl-exec
spences10
A
security
A
license
A
quality
A secure MCP server for Windows Subsystem for Linux environments, facilitating safe command execution with extensive validation and protection against vulnerabilities like shell injection and dangerous commands.
Last updated -
2
30
9
JavaScript
MIT License
Super Shell MCP Server
cfdude
-
security
A
license
-
quality
An MCP server that enables secure execution of shell commands across Windows, macOS, and Linux with built-in whitelisting and approval mechanisms for enhanced security.
Last updated -
13
JavaScript
MIT License
Kali Linux MCP Server
sfz009900
A
security
F
license
A
quality
A tool that allows penetration testing through Kali Linux commands executed via a Multi-Conversation Protocol server, supporting security testing operations like SQL injection and command execution.
Last updated -
5
5
TypeScript

View all related MCP servers