Exegol MCP Server

A Model Context Protocol (MCP) server that enables AI agents to interact with Exegol pentesting containers with predefined workflows for common pentesting tasks.

Features

Core Features

• ✅ Execute commands in Exegol containers (exegol exec -v)

• ✅ List available Exegol containers (exegol info)

• ✅ Health check and status monitoring

• ✅ 10-minute timeout for all command executions

• ✅ Concurrent execution support (5+ simultaneous commands)

• ✅ Structured JSON logging

🎯 Workflow Features (NEW!)

• ✅ 7 predefined pentesting workflows ready to use

• ✅ List workflows with filtering by category, difficulty, or tags

• ✅ Execute workflows with automatic step sequencing

• ✅ Workflows for: Web recon, subdomain enumeration, port scanning, vulnerability scanning, and more

• ✅ Automatic error handling with continue-on-failure support

Prerequisites

• Python 3.10+

• Exegol CLI installed and accessible (Exegol Installation)

• Docker running (required by Exegol)

• At least one Exegol container created

Verify prerequisites:

Installation

1. Clone or download this repository

2. Install dependencies:

3. Configure the server:

Configuration

Edit config.yaml:

Configuration Options Explained

Compact Mode (compact_mode: true)

• Purpose: Reduce token usage in AI responses

• Effect: Shorter field names, omits verbose metadata

• Recommended: true for Claude interactions

• Impact: ~30% reduction in response size

Auto-Parsing (auto_parse: true)

• Purpose: Intelligently parse pentesting tool outputs

• Supported tools: nmap, subfinder, gobuster, nuclei, and more

• Output: Adds structured parsed_output field to responses

• Benefit: Makes results easier to analyze and process

• Example:

  { "stdout": "...", "parsed_output": { "tool_detected": "nmap", "open_ports": ["22", "80", "443"], "services": { "22": "ssh", "80": "http", "443": "https" } } }

Persistent Sessions (sessions.enabled: true)

• Purpose: Reuse bash sessions across multiple commands

• Benefit: Faster execution, maintains environment state

• Use case: Multiple sequential commands on same container

• Idle timeout: Auto-close after 5 minutes of inactivity

Usage

Run as MCP Server

The server will start on stdio transport, ready for MCP client connections.

Integrate with Claude Desktop

Add to ~/.config/claude/mcp.json (Linux/Mac) or %APPDATA%\Claude\mcp.json (Windows):

Restart Claude Desktop, then try:

• "List available Exegol containers"

• "Execute 'whoami' in the pentest-box container"

Integrate with CLaude Code

Then use in claude code:

To check mcp status

🎯 Available MCP Tools

The server exposes 5 MCP tools:

Core Tools

1. exegol_exec - Execute a command in an Exegol container

2. exegol_list - List all available Exegol containers

3. exegol_status - Check MCP server health status

Workflow Tools

4. list_workflows - List available predefined pentesting workflows

5. run_workflow - Execute a complete pentesting workflow

📋 Predefined Workflows

Available Workflows

Workflow Usage Examples

1. List All Available Workflows

Ask Claude:

Claude will use the list_workflows MCP tool to show all 7 workflows with their details.

2. Execute a Web Reconnaissance Workflow

Ask Claude:

Claude will:

1. Use the run_workflow MCP tool

2. Specify workflow: web_recon

3. Set target: http://192.168.1.100

4. Execute all steps automatically:

   • Technology detection (whatweb)

   • Directory bruteforce (gobuster)

   • Web crawling (katana)

   • Comprehensive recon (finalrecon)

   • Display aggregated results

3. Filter Workflows by Category

Ask Claude:

Claude will use list_workflows with category filter to show only web-related workflows.

4. Execute Subdomain Enumeration

Ask Claude:

Claude will:

1. Run subdomain discovery (subfinder)

2. Check which subdomains are alive (httpx)

3. Display summary of findings

Workflow Parameters

Each workflow requires specific parameters:

Real-World Example

Scenario: You want to perform reconnaissance on a web application.

Ask Claude:

Claude will:

1. Detect technologies using whatweb

2. Bruteforce directories with gobuster

3. Crawl the website with katana

4. Run comprehensive reconnaissance with finalrecon

5. Show you all discovered endpoints, technologies, and potential attack vectors

Results you'll get:

• Detected web technologies (frameworks, libraries, versions)

• HTTP security headers analysis

• Discovered directories and files

• Crawled URLs

• JavaScript files and their contents

• Potential sensitive files exposed

Workflow Features

• ✅ Automatic step sequencing: Workflows execute multiple commands in order

• ✅ Error handling: Steps can continue on failure if configured

• ✅ Parameter validation: Validates required parameters before execution

• ✅ Detailed results: Each step returns stdout, stderr, exit code, and execution time

• ✅ Success tracking: Know exactly which steps succeeded or failed

Educational Use

This project is intended for educational purposes only. Always ensure you have permission to test any systems or networks.

License

This project is licensed under the MIT License.