Pentest

You can run a production-ready MCP server that lets AI agents perform autonomous penetration testing over SSH with persistent, tmux-backed sessions. It supports long-running workflows, interactive tool sessions, automatic reconnection, and careful resource management, so you can execute complex pentests across any Linux target with strong session durability.

How to use

Start the MCP server locally and connect your MCP client to the Python runtime. You will create persistent sessions, start interactive tools like msfconsole or reverse shells, and issue commands that run inside those sessions. Sessions survive network interruptions, allow multi-step workflows, and can be recovered after disconnections.

How to install

Prerequisites: you need Python and pip installed on your development machine. You will also need access to the target Linux system via SSH and tmux installed on the target.

# 1. Clone the MCP server repository
git clone https://github.com/LayeSec006/pentest-mcp-server.git
cd pentest-mcp-server

# 2. Install the MCP package in editable mode
pip install -e .

# 3. Prepare environment configuration
cp .env.example .env
# Edit .env with your target system details

# 4. Ensure tmux is installed on the target system
# (on Debian/Ubuntu/Kali/Parrot)
sudo apt update && sudo apt install tmux
# (on Arch/BlackArch)
sudo pacman -S tmux
# (on RHEL/CentOS/Fedora)
sudo yum install tmux
# (on newer Fedora/DNF-based)
sudo dnf install tmux
# (on Alpine)
sudo apk add tmux

# 5. Run tests to verify setup (optional)
python -m pytest tests/ -v

Configuration

Create a .env file with your target system details. This lets the MCP server know how to connect and how to manage resources.

# 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

MCP command and runtime

The MCP server is run as a local (stdio) process started by your client. Use Python to launch the MCP module so it can manage SSH connections, tmux sessions, and interactive tool workflows.

python -m pentest_mcp_server

Security considerations

Enable careful command filtering if you want to restrict dangerous operations. Define controlled commands and monitor session activity to prevent destructive actions.

Troubleshooting and tips

If you encounter connection or session issues, verify SSH connectivity to the target, check tmux availability on the target, and ensure your .env file contains valid host, user, and password (or SSH key) details. Use session recovery features to restore interrupted sessions after a network disruption.

Usage workflow examples

Typical workflows involve creating a persistent session, launching a tool inside that session, and optionally recovering the session after a disconnect. You can batch multiple tools in parallel or sequence them to build a multi-step pentest workflow.

Notes

This server is designed to provide persistent, interactive sessions for pentesting on Linux targets, with robust behavior during disconnections and reconnections. It supports a wide range of tools and complex workflows while enforcing resource limits to protect the host.

Available tools

create_session

Create a new persistent tmux session to isolate pentesting tasks.

list_sessions

List all active persistent sessions to monitor ongoing work.

kill_session

Terminate a specific persistent session and clean up resources.

execute

Run commands inside a persistent session, including long-running tools.

read_output

Fetch the current output from a running session to monitor progress.

send_input

Send interactive input to running tools inside a session.

get_system_status

Retrieve system resource usage and session status.

recover_sessions

Recover orphaned or interrupted sessions after reconnection.

upload_file

Upload files to the remote system via SFTP.

download_file

Download files from the remote system via SFTP.

parse_tool_output

Parse outputs from common pentest tools (e.g., nmap).