pentest

The Pentest MCP Server provides AI-assisted, persistent session control over a Linux target via SSH. It uses tmux-backed sessions to allow long-running, interactive pentesting workflows across tools like Metasploit, reverse shells, and other security utilities, all while recovering gracefully after disconnects or network issues. Agents can suspend and resume operations intelligently based on output patterns and triggers, with automatic SSH reconnection and smart resource management to prevent overloading the target.

To use it, run the MCP server module with the appropriate environment variables (target host, user, and credentials). Once running, integrate with your preferred MCP client (Claude Desktop, Windsurf, Cursor, or 5ire) by pointing the client to the pentest-mcp server and ensuring the same environment variables are available. The server exposes the persistent session manager and tool handlers (including msfconsole, MySQL access, reverse shells, and other installed utilities) so you can orchestrate complex, multi-step pentesting workflows through the MCP protocol.

Prerequisites:

• Python 3.10+ and pip
• SSH access to the target Linux host
• tmux installed on the target host
• Network access from the MCP server host to the target

Step-by-step installation:

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

# 2. Install the package in editable mode
python -m pip install --upgrade pip
pip install -e .

# 3. Configure environment (example)
cp .env.example .env
# Edit .env to set TARGET_HOST, TARGET_USER, TARGET_PASSWORD (or use SSH key via an alternative env if supported)

# 4. Ensure tmux is installed on the target
# From your machine, connect to the target and install tmux as needed
# Debian/Ubuntu/Kali/Parrot:
ssh kali@<TARGET_HOST>
sudo apt update && sudo apt install tmux
# Other distributions: use the appropriate package manager

# 5. Run tests (optional but recommended)
python -m pytest tests/ -v

Configure the MCP server (example):

# If you use an env file, ensure it contains:
# TARGET_HOST=192.168.1.100
# TARGET_USER=kali
# TARGET_PASSWORD=your_password

Start the server:

python -m pentest_mcp_server

You can also validate the installation by running tests or by connecting via your MCP client to verify the server boots and exposes the expected endpoints.

Tips and notes:

• Keep TARGET_PASSWORD secure; consider SSH keys if possible and adjust the environment accordingly.
• The server relies on tmux sessions; ensure the target system has enough resources for concurrent sessions (adjust MAX_SESSIONS and MAX_HEAVY_TASKS via your .env or config).
• If the MCP client cannot reconnect automatically, check network stability and SSH port access, and verify that the target host is reachable from the MCP server host.
• Use the provided integration snippets (Claude/Windsurf/Cursor/5ire) to wire up the server in your preferred UI; these integrations run the server module with the same env vars.
• For best results, ensure the target system has the tooling you plan to use (e.g., Metasploit, database services) installed and accessible within the SSH session.
• Review logs and check tmux session persistence if sessions unexpectedly terminate; the server is designed to recover sessions after crashes or disconnects.