# Pentest Mcp Server

> MCP server for penetration testing

- **Type:** MCP server
- **Install:** `agentstack add mcp-layesec006-pentest-mcp-server`
- **Verified:** Pending review
- **Seller:** [LayeSec006](https://agentstack.voostack.com/s/layesec006)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [LayeSec006](https://github.com/LayeSec006)
- **Source:** https://github.com/LayeSec006/pentest-mcp-server
- **Website:** https://github.com/LayeSec006/pentest-mcp-server

## Install

```sh
agentstack add mcp-layesec006-pentest-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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@

# 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
`

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [LayeSec006](https://github.com/LayeSec006)
- **Source:** [LayeSec006/pentest-mcp-server](https://github.com/LayeSec006/pentest-mcp-server)
- **License:** MIT
- **Homepage:** https://github.com/LayeSec006/pentest-mcp-server

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-layesec006-pentest-mcp-server
- Seller: https://agentstack.voostack.com/s/layesec006
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.