HackTheBox MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with programmatic access to HackTheBox platform functionality.

Features

The HTB MCP Server exposes 12 comprehensive tools for interacting with the HackTheBox platform:

Challenge Management

• list_challenges - Get paginated list of challenges with filtering
• start_challenge - Initialize a challenge environment
• submit_challenge_flag - Submit flags for challenge verification

Machine Management

• list_machines - Get active/retired machines with status information
• start_machine - Start a machine and get connection details
• get_machine_ip - Retrieve IP address of active machine
• submit_user_flag - Submit user flags for machines
• submit_root_flag - Submit root flags for machines

User Management

• get_user_profile - Retrieve user profile and statistics
• get_user_progress - Get completion status and achievements

Search & Utility

• search_content - Advanced search across challenges/machines/users
• get_server_status - Health check and server information

Prerequisites

• Go 1.21 or later
• Valid HackTheBox account with API access
• HTB API token (JWT format)

Installation

1. Clone the repository:

   git clone https://github.com/NoASLR/htb-mcp-server.git
   cd htb-mcp-server
   

2. Build the binary:

   go build -o htb-mcp-server main.go
   

3. Get your HTB API token:

   • Go to HackTheBox Profile Settings
   • Generate an App Token
   • Copy the JWT token (format: xxx.yyy.zzz)

Configuration

The server is configured via environment variables:

Required

• HTB_TOKEN - Your HackTheBox API token (JWT format)

Optional

• SERVER_PORT - Server port (default: 3000)
• LOG_LEVEL - Logging level: DEBUG, INFO, WARN, ERROR (default: INFO)
• RATE_LIMIT_PER_MINUTE - API rate limiting (default: 100)
• CACHE_TTL_SECONDS - Response cache TTL (default: 300)
• REQUEST_TIMEOUT_SECONDS - HTTP request timeout (default: 30)

Usage

Standalone Mode

export HTB_TOKEN="your.jwt.token.here"
./htb-mcp-server

Docker Mode

docker build -t htb-mcp-server .
docker run -e HTB_TOKEN="your.jwt.token.here" htb-mcp-server

MCP Client Integration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "htb": {
      "command": "/path/to/htb-mcp-server",
      "env": {
        "HTB_TOKEN": "your.jwt.token.here"
      }
    }
  }
}

Example Usage

Once connected, you can use the tools through your AI assistant:

# List active challenges
"Can you show me the available Web challenges on HackTheBox?"

# Start a machine
"Please start machine ID 123 and get its IP address"

# Submit a flag
"Submit the user flag 'HTB{example_flag}' for machine 123"

# Search for content
"Search for machines related to 'Active Directory'"

# Check server status
"What's the current status of the HTB MCP server?"

API Endpoints

The server implements the MCP protocol over stdio transport. All communication follows the JSON-RPC 2.0 specification.

Core MCP Methods

• initialize - Initialize the MCP session
• tools/list - List available tools
• tools/call - Execute a specific tool

HTB API Integration

The server integrates with HackTheBox API v4:

• Base URL: https://labs.hackthebox.com/api/v4
• Authentication: Bearer token (JWT)
• Rate limiting: Respects HTB API limits

Development

Project Structure

htb-mcp-server/
├── main.go                    # Entry point
├── pkg/
│   ├── config/               # Configuration management
│   ├── htb/                  # HTB API client
│   └── mcp/                  # MCP protocol implementation
├── internal/
│   ├── server/               # MCP server core
│   └── tools/                # Tool implementations
├── tests/       

... [View full README on GitHub](https://github.com/noaslr/htb-mcp-server#readme)