README.md

---
title: Kali Linux MCP Server
emoji: 🔒
colorFrom: red
colorTo: gray
sdk: docker
sdk_version: latest
app_port: 5000
---

# Kali Linux MCP Server

A Hugging Face Spaces deployment that hosts a Kali Linux environment with Model Context Protocol (MCP) support, allowing AI assistants like Cline to execute penetration testing tools remotely.

## Features

- **Kali Linux Environment**: Full Kali Linux with 20+ penetration testing tools
- **MCP Integration**: OpenAI-compatible API for AI assistants
- **Docker Deployment**: Ready for Hugging Face Spaces
- **Remote Tool Execution**: Execute nmap, sqlmap, metasploit, and more

## Included Tools

### Network Scanning & Enumeration
- **nmap** - Network discovery and security auditing
- **masscan** - Fast internet-scale port scanner

### Web Application Testing
- **gobuster** - Directory/file/DNS busting tool
- **dirb** - Web content scanner
- **nikto** - Web server scanner
- **sqlmap** - SQL injection exploitation tool

### Password Cracking
- **hydra** - Network logon cracker
- **john** - John the Ripper password cracker
- **hashcat** - Advanced password recovery

### Wireless Security
- **aircrack-ng** - Wireless network cracking suite

### Forensics & Analysis
- **binwalk** - Firmware analysis tool
- **radare2** - Reverse engineering framework
- **wireshark** - Network protocol analyzer

### Exploit Frameworks
- **metasploit-framework** - Penetration testing framework

### CMS Scanners
- **wpscan** - WordPress vulnerability scanner

### OSINT & Social Engineering
- **sherlock** - Username enumeration across social networks

### Web Exploitation
- **commix** - Command injection exploitation tool

### Miscellaneous
- **exploitdb** - Exploit database
- **steghide** - Steganography tool
- **cewl** - Custom wordlist generator
- **crunch** - Wordlist generator

## API Endpoints

### Health Check
```bash
GET /health
```

### Execute Command
```bash
POST /api/command
Content-Type: application/json

{
  "command": "nmap -sV 127.0.0.1"
}
```

### MCP Capabilities
```bash
GET /mcp/capabilities
```

## Usage with Cline

### Local Development
```bash
# Run the MCP server locally
python3 mcp_server.py
```

### Production Deployment
1. **Deploy to Hugging Face Spaces**
2. **Get your Space URL**: `https://your-username-kali-mcp.hf.space`
3. **Configure Cline MCP settings**:

```json
{
  "mcpServers": {
    "kali-tools": {
      "command": "python3",
      "args": ["/path/to/mcp_server.py"],
      "env": {
        "KALI_API_URL": "https://your-username-kali-mcp.hf.space"
      }
    }
  }
}
```

### Available Tools
- **execute_command**: Execute any shell command on Kali Linux
- **server_health**: Check server status and tool availability

The server exposes MCP-compatible endpoints that allow AI assistants to discover and execute Kali Linux tools.

## Technical Details

- **Base Image**: `kalilinux/kali-rolling`
- **Web Framework**: Flask
- **Protocol**: Model Context Protocol (MCP)
- **Timeout**: 180 seconds per command
- **Health Checks**: Automated monitoring

## Deployment

1. Create a new Hugging Face Space
2. Set SDK to "Docker"
3. Upload the Kali-MCP directory files
4. The Space will automatically build and deploy

## Security Notice

⚠️ **This tool is intended for educational and ethical testing purposes only.**

- Use only on systems you own or have explicit permission to test
- All activities are logged and monitored
- Unauthorized use may violate laws and platform terms

## Cost Considerations

- **Free Tier**: Basic functionality, limited resources
- **Paid Tiers**: Higher CPU/memory limits, persistent storage
- **GPU**: Not required for these tools

## Limitations

- Command execution timeout: 3 minutes
- No interactive sessions (use non-interactive flags)
- Memory limits based on Spaces tier
- No persistent file storage across sessions