# Pentest MCP Server
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](tests/)
A **production-ready** Model Context Protocol (MCP) server that enables AI agents to perform autonomous penetration testing on **ANY Linux distribution** via SSH. Built with persistent tmux sessions, intelligent triggers, auto-reconnection, and comprehensive resource management.
> **🚀 Key Differentiator:** Unlike other MCP servers that run commands independently, this server provides **persistent session management** with tmux, enabling complex interactive workflows and long-running operations.
## 📋 Table of Contents
- [👤 Connect](#-connect)
- [🖼️ Screenshots](#️-screenshots)
- [🎯 Core Capabilities](#-core-capabilities)
- [🎯 Key Features](#-key-features)
- [🎯 Real-World Impact](#-real-world-impact)
- [🏗️ Architecture](#️-architecture)
- [🚀 Quick Start](#-quick-start)
- [Installation (5 minutes)](#installation-5-minutes)
- [Configuration](#configuration)
- [AI Platform Integration](#ai-platform-integration)
- [🔧 Quick Setup](#-quick-setup)
- [🚀 Advanced Capabilities](#-advanced-capabilities)
- [🛠️ MCP Tools](#️-mcp-tools)
- [💡 Usage Examples](#-usage-examples)
- [🔒 Security Features](#-security-features)
- [🧪 Testing](#-testing)
- [📊 Monitoring & Debugging](#-monitoring--debugging)
- [🔧 Advanced Configuration](#-advanced-configuration)
- [🐛 Troubleshooting](#-troubleshooting)
- [🤝 Contributing](#-contributing)
- [📝 License](#-license)
- [⚠️ Legal Disclaimer](#️-legal-disclaimer)
- [🙏 Acknowledgments](#-acknowledgments)
## 👤 Connect
🎥 **Video Tutorial:** [Watch the complete walkthrough on YouTube](https://youtu.be/jDGuZIOjksc)
LinkedIn: [Abdallah Ndiaye](https://www.linkedin.com/in/abdallah-ndiaye-a3b98b380)
## 🖼️ Screenshots
## 🎯 **Core Capabilities**
This MCP server provides AI agents with **persistent session control** over ANY Linux distribution through SSH, enabling:
- **🌍 Universal Compatibility**: Works with Kali Linux, Parrot Security, BackBox, and ANY Linux distribution
- **🔓 Zero Tool Limitations**: Run ANY tool installed on the target system - no restrictions
- **🔄 Persistent Sessions**: Tmux-based sessions that survive disconnections and crashes
- **🤖 Intelligent Automation**: AI suspension/resumption based on output patterns and triggers
- **⚡ Auto-Reconnection**: Automatic SSH reconnection with exponential backoff
- **📊 Resource Management**: Smart limits on concurrent heavy operations
- **🎯 Interactive Tools**: Full support for msfconsole, mysql, reverse shells, and complex workflows
- **🛡️ Session Recovery**: Recover all sessions after crashes or network issues
## 🎯 **Key Features**
### **Our Core Advantages:**
- **🔄 Session Persistence**: Sessions survive disconnections and crashes
- **🎯 Interactive Tool Support**: Handle msfconsole, reverse shells, complex workflows
- **🤖 Intelligent Automation**: AI suspension/resumption with smart triggers
- **⚡ Auto-Reconnection**: Automatic recovery from network issues
- **📊 Resource Management**: Smart limits and system monitoring
- **🌍 Universal Compatibility**: Works with any Linux distribution
> **💡 The Advantage:** Our server provides **persistent session management** that enables complex, multi-step pentesting workflows with full interactive tool support.
## 🎯 **Real-World Impact**
### **What This Enables:**
- **Complex Workflows**: Multi-step pentesting operations that span hours
- **Interactive Tools**: Full Metasploit automation, reverse shell management
- **Session Persistence**: Long-running scans that survive network issues
- **Resource Management**: Smart limits on concurrent operations
- **Universal Deployment**: Works on any Linux distribution
### **Use Cases:**
- **Red Team Operations**: Automated reconnaissance and exploitation
- **CTF Challenges**: Complex multi-step problem solving
- **Security Research**: Long-running vulnerability assessments
- **AI-Assisted Pentesting**: Intelligent automation of repetitive tasks
## 🏗️ Architecture
```
┌─────────────────────┐
│ AI Agent │
│ (Claude/ChatGPT) │
└──────────┬──────────┘
│ MCP Protocol
▼
┌─────────────────────┐
│ MCP Server │
│ (Python) │
│ │
│ ┌───────────────┐ │
│ │Session Manager│ │
│ │Auto-Reconnect │ │
│ │Resource Mgmt │ │
│ └───────────────┘ │
└──────────┬──────────┘
│ SSH + PTY
▼
┌─────────────────────┐
│ Pentest System │
│ (Kali/Parrot/etc) │
│ │
│ ┌───────────────┐ │
│ │ tmux │ │
│ │ ┌─────────┐ │ │
│ │ │Session 1│ │ │
│ │ │Session 2│ │ │
│ │ │Session N│ │ │
│ │ └─────────┘ │ │
│ └───────────────┘ │
└─────────────────────┘
```
## 🚀 Quick Start
### Installation (5 minutes)
```bash
# 1. Clone repository
git clone https://github.com/LayeSec006/pentest-mcp-server.git
cd pentest-mcp-server
# 2. Install package
pip install -e .
# 3. Configure
cp .env.example .env
# Edit .env with your pentesting os details
# 4. Install tmux on target system
ssh kali@<TARGET_HOST>
# For Debian/Ubuntu/Kali/Parrot:
sudo apt update && sudo apt install tmux
# For Arch/BlackArch:
sudo pacman -S tmux
# For RHEL/CentOS/Fedora:
sudo yum install tmux
# OR for newer versions:
sudo dnf install tmux
# For Alpine Linux:
sudo apk add tmux
exit
# 5. Test
python -m pytest tests/ -v
```
### Configuration
Create a `.env` file with your target system details:
```env
# SSH Connection
TARGET_HOST=192.168.1.100
TARGET_PORT=22
TARGET_USER=kali
TARGET_PASSWORD=your_password
# OR use SSH key instead
# TARGET_SSH_KEY=/path/to/private/key
# Resource Limits
MAX_SESSIONS=20
MAX_HEAVY_TASKS=3
# Monitoring
POLL_INTERVAL=1.0
DEFAULT_TIMEOUT=300
```
## 🤖 AI Platform Integration
### Claude Desktop Integration
Add to your Claude Desktop configuration:
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"pentest-mcp": {
"command": "python",
"args": ["-m", "pentest_mcp_server"],
"env": {
"TARGET_HOST": "192.168.1.100",
"TARGET_USER": "kali",
"TARGET_PASSWORD": "your_password"
}
}
}
}
```
### Windsurf Integration
Add to your Windsurf settings:
```json
{
"mcpServers": {
"pentest-mcp": {
"command": "python",
"args": ["-m", "pentest_mcp_server"],
"env": {
"TARGET_HOST": "192.168.1.100",
"TARGET_USER": "kali",
"TARGET_PASSWORD": "your_password"
}
}
}
}
```
### Cursor Integration
Add to your Cursor settings:
```json
{
"mcpServers": {
"pentest-mcp": {
"command": "python",
"args": ["-m", "pentest_mcp_server"],
"env": {
"TARGET_HOST": "192.168.1.100",
"TARGET_USER": "kali",
"TARGET_PASSWORD": "your_password"
}
}
}
}
```
### 5ire Integration
In 5ire:
1. Click on **Tools** in the main interface
2. Click the **Local** button
3. Fill out the "Edit tool (Local Server)" form:
- **Tool Key:** `pentest-mcp`
- **Name:** `Pentest MCP` (optional)
- **Description:** `AI-powered penetration testing server` (optional)
- **Approval Policy:** Select `Always` (recommended)
- **Command:** `python -m pentest_mcp_server`
- **Environment Variables:**
- `TARGET_HOST` = `192.168.1.100`
- `TARGET_USER` = `kali`
- `TARGET_PASSWORD` = `your_password`
4. Review the **Config Preview** to ensure it's correct
5. Click **Save**
6. **Enable the tool:** Hover over the `pentest-mcp` entry in the Tools list and click the **toggle button** that appears on the right to enable it
```
### Warp AI Integration
In Warp terminal:
1. Go to **Settings** (⌘ + ,)
2. Click on **AI** in the sidebar
3. Scroll down to find **Manage MCP**
4. Click **Add MCP**
5. Paste this JSON configuration:
```json
{
"mcpServers": {
"pentest-mcp": {
"command": "python",
"args": ["-m", "pentest_mcp_server"],
"env": {
"TARGET_HOST": "192.168.1.100",
"TARGET_USER": "kali",
"TARGET_PASSWORD": "your_password"
}
}
}
}
```
6. Click **Save**
7. Restart Warp
## 🔧 Quick Setup
### Setup Steps
```bash
# 1. Clone and install
git clone https://github.com/LayeSec006/pentest-mcp-server.git
cd pentest-mcp-server
pip install -e .
# 2. Configure
cp .env.example .env
# Edit .env with your target system details
# 3. Test configuration
python -c "from pentest_mcp_server.config import Config; c = Config(); print('Config loaded:', c.TARGET_HOST)"
```
## 🚀 Advanced Capabilities
### 🎯 Interactive Tool Support
Start and interact with complex tools like Metasploit Framework:
```json
{
"tool": "execute",
"args": {
"session_id": "msf_session",
"command": "msfconsole -q"
}
}
```
Interact with the running tool:
```json
{
"tool": "send_input",
"args": {
"session_id": "msf_session",
"input": "use exploit/multi/handler"
}
}
```
### 🔄 Reverse Shell Management
Handle incoming reverse shells seamlessly:
```json
{
"tool": "execute",
"args": {
"session_id": "reverse_shell",
"command": "nc -lvp 4444"
}
}
```
Interact with connected shells:
```json
{
"tool": "send_input",
"args": {
"session_id": "reverse_shell",
"input": "whoami"
}
}
```
### 📊 Complex Workflow Automation
Support for multi-step pentesting workflows:
1. **Network reconnaissance** (nmap, masscan)
2. **Web application scanning** (gobuster, nikto, dirb)
3. **Vulnerability exploitation** (metasploit, custom exploits)
4. **Post-exploitation** (meterpreter, privilege escalation)
5. **Data exfiltration** (file operations, tunneling)
### 🛡️ Session Persistence & Recovery
Sessions survive network interruptions and crashes:
```json
{
"tool": "recover_sessions",
"args": {}
}
```
**Key Benefits:**
- Sessions continue running even if SSH connection drops
- Automatic reconnection with exponential backoff
- State preservation across network issues
- Full recovery of interactive sessions
## 🛠️ MCP Tools
### Session Management
| Tool | Description | Purpose |
|------|-------------|----------|
| `create_session` | Create new persistent tmux session | Start isolated workspace for pentesting tasks |
| `list_sessions` | List all active sessions | Monitor running operations |
| `kill_session` | Terminate specific session | Clean up completed tasks |
#### `create_session`
Create a new persistent tmux session for isolated pentesting operations.
**Parameters:**
```json
{
"session_id": "scan_network",
"shell": "bash"
}
```
#### `list_sessions`
List all active tmux sessions and their status.
**Parameters:**
```json
{}
```
#### `kill_session`
Terminate a specific session and clean up resources.
**Parameters:**
```json
{
"session_id": "scan_network"
}
```
### Command Execution
| Tool | Description | Purpose |
|------|-------------|----------|
| `execute` | Execute commands in persistent sessions | Run pentesting tools and scripts |
| `read_output` | Get current output from session | Monitor command progress and results |
| `send_input` | Send input to interactive tools | Control interactive applications |
#### `execute`
Execute commands in persistent sessions.
```json
{
"session_id": "scan_network",
"command": "nmap -sV 192.168.1.0/24",
"background": false
}
```
#### `read_output`
Get current output from a session.
```json
{
"session_id": "scan_network",
"lines": 50
}
```
#### `send_input`
Send input to interactive tools.
```json
{
"session_id": "msf_session",
"input": "use exploit/multi/handler",
"press_enter": true
}
```
### System Management
#### `get_system_status`
Get system resource usage and session status.
```json
{}
```
#### `recover_sessions`
Recover orphaned sessions after reconnection.
```json
{}
```
### File Operations
#### `upload_file`
Upload files to your system via SFTP.
```json
{
"local_path": "/path/to/local/file",
"remote_path": "/tmp/uploaded_file"
}
```
#### `download_file`
Download files from your system via SFTP.
```json
{
"remote_path": "/tmp/scan_results.xml",
"local_path": "/path/to/local/results.xml"
}
```
### Tool Output Parsing
#### `parse_tool_output`
Parse common pentest tool outputs (nmap XML, JSON, etc.).
```json
{
"tool": "nmap",
"file_path": "/tmp/scan.xml",
"format": "xml"
}
```
## 💡 Usage Examples
### Basic Network Scan
```
AI: I need to scan the network 192.168.1.0/24
Tool: create_session
Args: {"session_id": "network_scan"}
Tool: execute
Args: {
"session_id": "network_scan",
"command": "nmap -sV 192.168.1.0/24 -oX /tmp/scan.xml"
}
Tool: read_output
Args: {"session_id": "network_scan"}
```
### Interactive Metasploit Usage
```
AI: Let me start Metasploit and set up a handler
Tool: create_session
Args: {"session_id": "metasploit"}
Tool: execute
Args: {
"session_id": "metasploit",
"command": "msfconsole -q"
}
Tool: send_input
Args: {
"session_id": "metasploit",
"input": "use exploit/multi/handler"
}
Tool: send_input
Args: {
"session_id": "metasploit",
"input": "set PAYLOAD linux/x64/meterpreter/reverse_tcp"
}
Tool: send_input
Args: {
"session_id": "metasploit",
"input": "exploit"
}
```
### Parallel Operations
```
AI: I'll run multiple scans in parallel
Tool: create_session
Args: {"session_id": "nmap_scan"}
Tool: create_session
Args: {"session_id": "gobuster_scan"}
Tool: execute
Args: {
"session_id": "nmap_scan",
"command": "nmap -p- 192.168.1.5",
"background": true
}
Tool: execute
Args: {
"session_id": "gobuster_scan",
"command": "gobuster dir -u http://192.168.1.5 -w /usr/share/wordlists/dirb/common.txt",
"background": true
}
```
## 🔒 Security Features
### Command Filtering (Optional)
The server can optionally block dangerous commands:
- `rm -rf /` - Recursive delete from root
- `dd if=...of=/dev/sd*` - Disk wiping commands
- `mkfs` - Filesystem formatting
- Fork bombs and other destructive patterns
## 🧪 Testing
Run the test suite:
```bash
# Install test dependencies
pip install pytest pytest-asyncio pytest-mock
# Run tests
python -m pytest tests/ -v
# Run with coverage
python -m pytest tests/ --cov=pentest_mcp_server --cov-report=html
```
### Test Categories
- **Unit Tests**: Individual component testing
- **Integration Tests**: End-to-end workflow testing
- **Connection Tests**: SSH and reconnection scenarios
- **Session Tests**: Tmux session management
## 📊 Monitoring & Debugging
### Logging
The server provides detailed logging:
```python
import logging
logging.basicConfig(level=logging.INFO)
```
Log levels:
- `INFO`: Connection status, session creation/destruction
- `WARNING`: Reconnection attempts, blocked commands
- `ERROR`: Connection failures, command errors
- `DEBUG`: Detailed protocol messages
### System Status
Use the `get_system_status` tool to monitor:
- CPU and memory usage
- Active session count
- Connection health
- Recent command history
### Session Recovery
After crashes or network issues:
```
Tool: recover_sessions
Args: {}
Response: {
"status": "success",
"recovered_sessions": [
{
"session_id": "network_scan",
"age_seconds": 1800,
"last_output": "...Nmap scan report..."
}
]
}
```
## 🔧 Advanced Configuration
### Resource Management
```env
# Limit concurrent heavy operations
MAX_HEAVY_TASKS=3
# Heavy commands that count against the limit
HEAVY_COMMANDS=nmap,masscan,hydra,john,hashcat,sqlmap
```
### Connection Tuning
```env
# Reconnection settings
MAX_RECONNECT_ATTEMPTS=5
RECONNECT_DELAY_BASE=2 # Exponential backoff base
# Health check interval
POLL_INTERVAL=1.0
# Default command timeout
DEFAULT_TIMEOUT=300
```
### Tmux Customization
```env
# Custom tmux socket name
TMUX_SOCKET_NAME=mcp-pentest
# Session persistence location
TMUX_SESSION_PATH=/tmp/mcp-sessions
```
## 🐛 Troubleshooting
### Common Issues
**Connection Refused**
```
Error: Connection failed: [Errno 111] Connection refused
```
- Verify SSH is running on your system: `service ssh status`
- Check firewall rules: `ufw status`
- Verify host/port in configuration
**Authentication Failed**
```
Error: Permission denied (publickey,password)
```
- Verify username/password are correct
- Check SSH key permissions (600)
- Enable password auth: `PasswordAuthentication yes` in `/etc/ssh/sshd_config`
**Tmux Not Found**
```
Error: tmux is not installed on target system
```
- Install tmux on your distro: `apt update && apt install tmux`
**Session Lost**
```
Error: Session 'scan_network' does not exist
```
- Use `recover_sessions` tool to find orphaned sessions
- Check if the system rebooted (sessions don't survive reboot)
### Debug Mode
Enable verbose logging:
```python
import logging
logging.getLogger('pentest_mcp_server').setLevel(logging.DEBUG)
logging.getLogger('asyncssh').setLevel(logging.DEBUG)
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Run tests (`python -m pytest tests/`)
4. Commit changes (`git commit -m 'Add amazing feature'`)
5. Push to branch (`git push origin feature/amazing-feature`)
6. Open a Pull Request
### Development Setup
```bash
git clone <your-fork>
cd pentest_mcp_server
pip install -e .
pip install pytest pytest-asyncio pytest-mock
```
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## ⚠️ Legal Disclaimer
This tool is intended for authorized security testing and educational purposes only. Users are responsible for ensuring they have proper authorization before using this tool against any systems. The developers are not responsible for any misuse or damage caused by this tool.
## 🙏 Acknowledgments
- Based on [t-suganuma/ssh-connect-mcp-server](https://github.com/t-suganuma/ssh-connect-mcp-server)
- Built with [asyncssh](https://asyncssh.readthedocs.io/) for superior SSH handling
- Uses [tmux](https://github.com/tmux/tmux) for persistent sessions
- Implements [Model Context Protocol](https://modelcontextprotocol.io/) specification
---
**Happy Pentesting! 🔒🔓**
