# Kali Linux MCP Server
A Model Context Protocol (MCP) server that exposes 60+ Kali Linux security tools through an AI-friendly interface. Enables AI assistants like Claude to perform penetration testing and security assessments.
## Features
**Network Scanning**: nmap, masscan, netdiscover, hping3, tcpdump, tshark
**Web Security**: gobuster, nikto, sqlmap, wpscan, burpsuite, zap, ffuf, nuclei
**Password Cracking**: hydra, john, hashcat, medusa, crackmapexec
**Exploitation**: metasploit, searchsploit, beef, routersploit
**Wireless**: aircrack-ng, reaver, wifite, kismet
**Windows/AD**: enum4linux, impacket, evil-winrm, kerbrute, mimikatz, responder
**OSINT**: theharvester, shodan, spiderfoot, amass, sublist3r
**Forensics**: binwalk, foremost
**Plus**: shells (netcat, socat, msfvenom), anonymity (proxychains), mobile (apktool)
## Quick Start
### Docker (Recommended)
```bash
# Start Kali API server
make run
# Or manually
docker-compose up -d
python mcp_http_server.py
```
### Manual Setup
```bash
# Install dependencies
pip install -r requirements.txt
# Run Kali API server (requires Kali Linux)
python kali_server.py
# Run MCP HTTP server
python mcp_http_server.py --kali-server http://localhost:5001
```
### Configure Cursor/Claude
Add to your MCP settings:
```json
{
"mcpServers": {
"kali-tools": {
"url": "http://localhost:5002/sse"
}
}
}
```
## Architecture
- **kali_server.py**: Flask REST API exposing Kali tools
- **mcp_http_server.py**: MCP-over-HTTP bridge to Kali API
- **server/tools/**: Tool implementations organized by category
- **Docker**: Kali Linux container with all tools pre-installed
## Requirements
- Python 3.8+
- Docker (for containerized deployment)
- Kali Linux environment (for manual setup)
## Testing
The project includes a comprehensive test suite using pytest.
### Quick Start
```bash
# Setup test environment
./scripts/setup_tests.sh
# Run all tests
make test
# Run with coverage
make test-coverage
# Run only unit tests (fast)
make test-unit
# Run integration tests
make test-integration
```
### Test Structure
```
tests/
├── test_kali_client.py # HTTP client tests
├── test_kali_server.py # Flask API endpoint tests
├── test_command_executor.py # Command execution tests
├── test_mcp_server.py # MCP server setup tests
├── test_integration.py # Integration tests
└── test_tools/ # Tool-specific tests
├── test_network_scanning.py
├── test_web_scanning.py
└── test_password_cracking.py
```
### Available Test Commands
```bash
make test # Run all tests
make test-unit # Run unit tests only
make test-integration # Run integration tests only
make test-coverage # Run tests with coverage report
make test-file FILE=tests/test_kali_client.py # Run specific file
make clean # Clean up test artifacts
make help # Show all available commands
```
### Coverage Reports
After running `make test-coverage`, view the HTML report:
```bash
open htmlcov/index.html
```
### Continuous Integration
Tests run automatically on GitHub Actions for:
- Multiple Python versions (3.9, 3.10, 3.11, 3.12)
- Every push to main/develop branches
- All pull requests
See [tests/README.md](tests/README.md) for detailed testing documentation.
## License
MIT License - See LICENSE file
