Kali Linux MCP Server

A Model Context Protocol (MCP) server that provides access to Kali Linux security tools through a Docker container. This server allows you to run penetration testing and security assessment tools in a controlled, containerized environment.

Features

• Containerized Security Tools: Access to popular Kali Linux tools through Docker
• MCP Integration: Compatible with MCP clients like Claude Desktop
• Safe Execution: Tools run in an isolated Docker container
• Comprehensive Tool Set: Includes nmap, gobuster, sqlmap, hydra, nuclei, and more
• Resource Management: Built-in container lifecycle management

Available Tools

Network Scanning

• nmap_scan: Perform network scanning with various scan types
• masscan: High-speed port scanning
• nuclei_scan: Vulnerability scanning with Nuclei templates

Web Application Testing

• gobuster_scan: Directory and file bruteforcing
• sqlmap_scan: SQL injection vulnerability testing
• nikto: Web server vulnerability scanning

Authentication Testing

• hydra_bruteforce: Password bruteforcing for various services

General Purpose

• execute_command: Execute any command in the Kali container

Prerequisites

• Docker and Docker Compose installed
• Node.js 18+ for development
• MCP-compatible client (e.g., Claude Desktop)

Installation

1. Clone or navigate to the project directory:

   cd "Virtual Machines.localized/docker/kali"
   

2. Install Node.js dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Quick Start

Option 1: Using Docker Compose (Recommended)

1. Start the Kali container:

   npm run docker:compose
   

2. Run the MCP server:

   npm start
   

Option 2: Manual Docker Management

1. Build the Docker image:

   npm run docker:build
   

2. Start the container:

   npm run docker:run
   

3. Run the MCP server:

   npm start
   

Usage Examples

Network Scanning with Nmap

{
  "name": "nmap_scan",
  "arguments": {
    "target": "192.168.1.1",
    "scan_type": "tcp",
    "ports": "80,443,22,21"
  }
}

Directory Bruteforcing with Gobuster

{
  "name": "gobuster_scan",
  "arguments": {
    "url": "http://example.com",
    "wordlist": "common",
    "extensions": "php,html,js",
    "threads": 20
  }
}

SQL Injection Testing with SQLMap

{
  "name": "sqlmap_scan",
  "arguments": {
    "url": "http://example.com/login.php",
    "data": "username=admin&password=test",
    "level": 3,
    "risk": 2
  }
}

Password Bruteforcing with Hydra

{
  "name": "hydra_bruteforce",
  "arguments": {
    "target": "192.168.1.100",
    "service": "ssh",
    "username": "admin",
    "password_list": "common",
    "threads": 4
  }
}

Vulnerability Scanning with Nuclei

{
  "name": "nuclei_scan",
  "arguments": {
    "target": "https://example.com",
    "templates": "cves",
    "severity": "high"
  }
}

Custom Command Execution

{
  "name": "execute_command",
  "arguments": {
    "command": "searchsploit apache",
    "working_dir": "/home/kali"
  }
}

Configuration for Claude Desktop

Add this to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "kali-linux": {
      "command": "node",
      "args": ["/path/to/kali-linux-mcp-server/build/index.js"],
      "cwd": "/path/to/kali-linux-mcp-server"
    }
  }
}

Available Resources

The server provides several resources for information gathering:

• kali://wordlists: List available wordlists in the container
• kali://tools: Show installed security tools and their status
• kali://container-info: Display container information and status

Development

Running in Development Mode

npm run dev

Building the Project

npm run build

Managing Docker Containers

• Start container: npm run docker:compose
• Stop container: npm run docker:compose:down
• Rebuild image: npm run docker:build

Security Considerations

⚠️ Important Security Notes:

1. Ethical Use Only: This tool is intended for authorized security testing only
2. Isolated Environment: All tools run in a containerized environment
3. Network Isolation: Consider network isolation for sensitive environments
4. Resource Limits: Container has resource limits to prevent abuse
5. No Root Access: Tools run as non-root user within the container

Troubleshooting

Container Issues

1. Container not starting:

   docker logs kali-mcp-container
   

2. Image build failures:

   docker system prune
   npm run docker:build
   

3. Permission errors:

   docker exec -it kali-mcp-container chown -R kali:kali /home/kali
   

MCP Server Issues

1. Module not found errors: Ensure dependencies are installed with npm install
2. TypeScript compilation errors: Run npm run build to compile
3. Docker connection errors: Verify Docker is running and accessible

Tool-Specific Notes

Nmap

• Requires appropriate permissions for certain scan types
• SYN scans may require root privileges (handled automatically)
• Large scan ranges may take significant time

SQLMap

• Batch mode is enabled by default to prevent interactive prompts
• Test responsibly and only on systems you own or have permission to test

Hydra

• Rate limiting is important to avoid detection
• Use appropriate thread counts for target systems

Nuclei

• Templates are automatically updated during image build
• Severity filtering helps focus on important findings

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Disclaimer

This tool is for educational and authorized security testing purposes only. Users are responsible for complying with all applicable laws and regulations. The authors are not responsible for any misuse of this software.