MCP Kali Server
A comprehensive Model Context Protocol (MCP) server for penetration testing and cybersecurity operations, providing seamless integration between Kali Linux tools and MCP-compatible clients.
🎥 Demo Video
Automating Kali Linux with an MCP (Model Context Protocol) — HTB Demo
In this video, I showcase how my MCP automates a Kali Linux workflow inside WSL2 and assists with solving a Hack The Box challenge — from enumeration to exploitation to auto-generated documentation.
🚀 Overview
This project provides a powerful MCP server that enables secure, programmatic access to Kali Linux penetration testing tools through a standardized interface. It includes advanced features like reverse shell management, SSH session handling, and comprehensive file operations with integrity verification.
🏗️ Architecture
This project is designed to work across different environments:
1. Kali Server (kali-server/)
Runs on Kali Linux only - The core server application that provides the actual penetration testing capabilities.
kali-server/
├── api/ # REST API routes and endpoints
├── core/ # Core functionality (SSH, reverse shells, config, Docker)
├── tools/ # Penetration testing tools integration
└── utils/ # Utility functions and file operations
Features:
- Docker test mode (
--testoption) - automatically manages test containers - All penetration testing tools (nmap, gobuster, etc.)
- SSH and reverse shell session management
- File operations with integrity verification
2. MCP Server (mcp-server/)
Can run on any system - The Model Context Protocol server that provides a standardized interface for MCP clients.
mcp-server/
└── mcp_server.py # MCP protocol implementation
Note: The MCP server communicates with the Kali server via HTTP, so they can be on different systems.
Deployment Architecture
┌─────────────────┐ HTTP ┌──────────────────┐ HTTP ┌──────────────────┐
│ MCP Client │ ◄─────────► │ MCP Server │ ◄─────────► │ Kali Server │
│ (Any system) │ │ (Any system) │ │ (Kali Linux) │
└─────────────────┘ └──────────────────┘ │ │
│ ┌──────────────┐ │
│ │ Docker │ │
│ │ (test mode) │ │
│ └──────────────┘ │
└──────────────────┘
✨ Key Features
🔧 Penetration Testing Tools
- Nmap: Network discovery and security auditing
- Gobuster: Directory/file enumeration
- Dirb: Web content scanner
- Nikto: Web server scanner
- Hydra: Network logon cracker
- SQLmap: SQL injection testing
- WPScan: WordPress security scanner
- John the Ripper: Password cracking
- Enum4linux: SMB enumeration
- Metasploit: Exploitation framework
🐚 Advanced Session Management
- SSH Session Manager: Complete SSH session lifecycle management
start_ssh_session: Establish secure SSH connectionsexecute_ssh_command: Run commands in SSH sessionsget_ssh_status: Monitor SSH session statusstop_ssh_session: Cleanly terminate SSH sessionslist_ssh_sessions: View all active SSH sessions
- Reverse Shell Manager: Multi-session reverse shell handling
start_reverse_shell_listener: Start listening for reverse shellsexecute_shell_command: Execute commands in reverse shellstrigger_reverse_shell_action: Non-blocking trigger execution for payloadsget_shell_status: Monitor reverse shell session statusstop_reverse_shell: Terminate reverse shell sessionslist_reverse_shell_sessions: View all active reverse shell sessions
📁 Comprehensive File Operations
- Kali Server File Management:
upload_to_kali: Upload files directly to Kali serverdownload_from_kali: Download files from Kali server
- SSH File Transfer (optimized for large files):
ssh_upload_content: Upload content via SSH with auto-optimizationssh_download_content: Download content via SSH with chunkingssh_estimate_transfer_time: Estimate transfer times and get recommendations
- Reverse Shell File Transfer:
reverse_shell_upload_file: Upload files via reverse shellreverse_shell_upload_content: Upload content via reverse shellreverse_shell_download_file: Download files via reverse shellreverse_shell_download_content: Download content via reverse shell
🛠️ System Integration
- Command Execution: Direct command execution on Kali server
- Health Monitoring: Server health checks and status monitoring
- Session Persistence: Maintain multiple concurrent sessions
🔒 Security Features
- Data Integrity: SHA256 checksum verification for all file transfers
- Secure Communications: Encrypted SSH connections
- Session Isolation: Independent session management
- Error Handling: Comprehensive error detection and reporting
📊 Performance Optimization
- Chunked Transfers: Optimized for large file operations
- Automatic Method Selection: Smart selection based on file size
- Background Processing: Non-blocking operations for long-running tasks
- Resource Management: Efficient memory and CPU usage
🛠️ Installation
See install.md for detailed installation instructions.
MCP Client Configuration
After installation, configure your MCP client to connect to the Kali server:
This guide covers:
- Setting up
.claude/mcp_settings.jsonfor Claude Desktop - Configuring alternative MCP clients
- Finding your Python path and Kali IP address
- Platform-specific examples (Windows, Linux, macOS)
WSL Network Configuration
If you're running Kali Linux in WSL 2, proper network configuration is critical for the MCP server to function. See our comprehensive guide:
📖 WSL Network Configuration Guide
This guide covers:
- Essential WSL configuration (
wsl.conf) - DNS resolution setup for Kali tools
- Critical: Understanding WSL 2 localhost behavior (Windows → Kali communication)
- Network testing and troubleshooting
⚠️ Important: The MCP client on Windows must be able to access the Kali server via localhost. Review this guide before running the server.
Dependency Split
This project now separates Python dependencies for the two runtime components:
requirements.kali.txt– Only what the Kali API server Python code needs (Flask, etc.)requirements.mcp.txt– Dependencies for the MCP server client interface (requests, FastMCP, test libs)requirements.txt– Informational file describing the split; contains no direct packages now.
Install on each machine as appropriate:
pip install -r requirements.kali.txt # On Kali host running kali-server/
pip install -r requirements.mcp.txt # On host running mcp-server/
⚠️ Security Warning
IMPORTANT: Be extremely cautious when running the Kali server with sudo privileges:
# ⚠️ DANGEROUS - Avoid if possible
sudo python kali_server.py
Why this is risky:
- The entire server runs with root privileges
- All API endpoints and commands execute with full system access
- Any compromise of the server grants complete root access to the system
- No privilege separation or access control
Safer alternatives:
- Run the server as a regular user (many tools work without root)
- Use specific sudo permissions only for commands that require them
- Consider containerization or virtualization for isolation
- Implement privilege escalation only when absolutely necessary
For production environments: Please see TODO.md for planned security enhancements including granular privilege management and access controls.
📖 Usage
See usage.md for detailed usage instructions and examples.
🧪 Testing
The project includes comprehensive test suites using Docker containers for isolated testing environments.
Run All Tests
cd tests
./run_all.bat # Windows
# or
chmod +x run_all.sh && ./run_all.sh # Linux
Docker Testing Environment
cd tests/docker
docker-compose up -d --build
python test_config_docker.py
SSH Manager Tests
cd tests/kali
python -m pytest test_ssh_manager.py -v
Test Configuration
Tests use Docker containers for consistent and isolated testing environments. The configuration is automatically set up in:
tests/kali/test_config.py- Main test configuration (Docker-based)tests/docker/test_config_docker.py- Docker-specific test configuration
📋 Available MCP Tools
The MCP server provides the following tools:
🔍 File Operations
Upload with Integrity Verification
# The system automatically verifies file integrity using SHA256 checksums
upload_result = {
"success": True,
"source_checksum": "abc123...",
"remote_checksum": "abc123...",
"checksum_verified": True,
"integrity_check": "PASSED"
}
Download with Integrity Verification
# All downloads include automatic integrity verification
download_result = {
"success": True,
"remote_checksum": "def456...",
"local_checksum": "def456...",
"checksum_verified": True,
"integrity_check": "PASSED"
}
🚨 Security Considerations
- Testing Environment: All tests use isolated Docker containers for security
- Network Security: Ensure proper firewall configuration
- Authentication: Use strong passwords and key-based authentication
- Session Management: Regularly clean up unused sessions
- File Permissions: Set appropriate file permissions on uploaded files
- Logging: Monitor all activities through comprehensive logging
🐛 Troubleshooting
Common Issues
-
Connection Refused
# Check if server is running curl http://localhost:5000/health -
SSH Connection Failed
# Verify SSH connectivity ssh user@target-host -
Tool Not Found
# Install missing tools sudo apt update && sudo apt install nmap gobuster -
Docker Test Mode Issues
If you encounter Docker-related errors when using
--testmode on Kali Linux:Common Docker fixes on Kali Linux:
# Install Docker sudo apt update && sudo apt install docker.io # Start Docker service sudo systemctl start docker sudo systemctl enable docker # Add user to docker group (then logout/login) sudo usermod -aG docker $USER # Test Docker access docker --version docker psIf Docker commands work manually but fail in test mode:
- The issue might be PATH-related in the Python environment
- Try running with sudo:
sudo python kali_server.py --test - Check Docker socket permissions:
ls -la /var/run/docker.sock - Ensure you're running this on Kali Linux, not Windows
Debug Mode
Enable debug logging:
# For the server
python kali_server.py --test --debug
# For Python logging
import logging
logging.basicConfig(level=logging.DEBUG)
🤝 Contributing
- Fork the repository
- Create a feature branch
- Follow the coding standards (English comments, proper naming)
- Add comprehensive tests
- Update documentation
- Submit a pull request
Coding Standards
- All code, variables, and functions must be in English
- All comments and documentation must be in clear English
- Follow standard naming conventions
- Add tests for new features or bug fixes
- Update README and documentation
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- Original Project: This project is initially a fork of MCP-Kali-Server but has been completely rewritten and restructured
- Kali Linux for the comprehensive penetration testing platform
- Model Context Protocol for the standardized interface
- The cybersecurity community for continuous tool development
📞 Support
- Issues: GitHub Issues
- Documentation: Wiki
⚠️ Disclaimer: This tool is designed for authorized penetration testing and security research only. Users are responsible for complying with applicable laws and regulations.
