# 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**:
   ```bash
   cd "Virtual Machines.localized/docker/kali"
   ```

2. **Install Node.js dependencies**:
   ```bash
   npm install
   ```

3. **Build the project**:
   ```bash
   npm run build
   ```

## Quick Start

### Option 1: Using Docker Compose (Recommended)

1. **Start the Kali container**:
   ```bash
   npm run docker:compose
   ```

2. **Run the MCP server**:
   ```bash
   npm start
   ```

### Option 2: Manual Docker Management

1. **Build the Docker image**:
   ```bash
   npm run docker:build
   ```

2. **Start the container**:
   ```bash
   npm run docker:run
   ```

3. **Run the MCP server**:
   ```bash
   npm start
   ```

## Usage Examples

### Network Scanning with Nmap

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

### Directory Bruteforcing with Gobuster

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

### SQL Injection Testing with SQLMap

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

### Password Bruteforcing with Hydra

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

### Vulnerability Scanning with Nuclei

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

### Custom Command Execution

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

## Configuration for Claude Desktop

Add this to your Claude Desktop MCP configuration:

```json
{
  "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

```bash
npm run dev
```

### Building the Project

```bash
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**:
   ```bash
   docker logs kali-mcp-container
   ```

2. **Image build failures**:
   ```bash
   docker system prune
   npm run docker:build
   ```

3. **Permission errors**:
   ```bash
   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.