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:

python3 --version  # Should be 3.10+
exegol --version   # Should show Exegol version
docker ps          # Should show Docker is running
exegol info        # Should list Exegol containers

Installation

1. Clone or download this repository
2. Install dependencies:

pip install -r requirements.txt

3. Configure the server:

# Edit config.yaml to set your Exegol path
vim config.yaml

Configuration

Edit config.yaml:

exegol:
  path: "exegol"  # or /usr/local/bin/exegol

timeout:
  command_execution: 600  # 10 minutes

logging:
  level: "INFO"  # DEBUG, INFO, WARNING, ERROR
  format: "json"  # json or text

mcp:
  server_name: "exegol-mcp-server"
  version: "0.1.0"

  # Compact mode: reduce token usage (recommended for Claude)
  compact_mode: true

sessions:
  # Persistent sessions: reuse bash sessions (more efficient)
  enabled: false
  idle_timeout: 300  # Close after 5 minutes of inactivity

parsing:
  # Auto-parse pentest tool outputs (nmap, subfinder, gobuster, etc.)
  auto_parse: true

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

python exegol_mcp.py

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

{
  "mcpServers": {
    "exegol": {
      "command": "python",
      "args": ["/absolute/path/to/exegol_mcp.py"]
    }
  }
}

Restart Claude Desktop, then try:

• "List available Exegol containers"
• "Execute 'whoami' in the pentest-box container"

Integrate with CLaude Code

claude mcp add --transport stdio exegol-mcp -- python /absolute/path/to/exegol_mcp.py

Then use in claude code:

/mcp

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:

List all available pentesting workflows

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

2. Execute a Web Reconnaissance Workflow

Ask Claude:

Run the web_recon workflow on http://192.168.1.100

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:

Show me all web pentesting workflows

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

4. Execute Subdomain Enumeration

Ask Claude:

Enumerate subdomains for example.com using the recon_subdomain workflow

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:

I need to scan http://192.168.1.100:8080 for reconnaissance.
Use the web_recon workflow.

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.