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.

Claude Kali Integration