Pentest Mcp Server

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

LinkedIn: Abdallah Ndiaye

🖼️ 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)

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

# 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

{
  "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:

{
  "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:

{
  "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

1. Review the Config Preview to ensure it's correct
2. Click Save
3. 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"
      }
    }
  }
}

1. Click Save
2. Restart Warp

🔧 Quick Setup

Setup Steps

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

{
  "tool": "execute",
  "args": {
    "session_id": "msf_session",
    "command": "msfconsole -q"
  }
}

Interact with the running tool:

{
  "tool": "send_input",
  "args": {
    "session_id": "msf_session",
    "input": "use exploit/multi/handler"
  }
}

🔄 Reverse Shell Management

Handle incoming reverse shells seamlessly:

{
  "tool": "execute",
  "args": {
    "session_id": "reverse_shell",
    "command": "nc -lvp 4444"
  }
}

Interact with connected shells:

{
  "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:

{
  "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:

{
  "session_id": "scan_network",
  "shell": "bash"
}

list_sessions

List all active tmux sessions and their status.

Parameters:

{}

kill_session

Terminate a specific session and clean up resources.

Parameters:

{
  "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.

{
  "session_id": "scan_network",
  "command": "nmap -sV 192.168.1.0/24",
  "background": false
}

read_output

Get current output from a session.

{
  "session_id": "scan_network",
  "lines": 50
}

send_input

Send input to interactive tools.

{
  "session_id": "msf_session",
  "input": "use exploit/multi/handler",
  "press_enter": true
}

System Management

get_system_status

Get system resource usage and session status.

{}

recover_sessions

Recover orphaned sessions after reconnection.

{}

File Operations

upload_file

Upload files to your system via SFTP.

{
  "local_path": "/path/to/local/file",
  "remote_path": "/tmp/uploaded_file"
}

download_file

Download files from your system via SFTP.

{
  "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.).

{
  "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:

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

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

# 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

# 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

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