htb-mcp

htb-mcp is an MCP server for Hack The Box.
It wraps HTB API operations as MCP tools so assistants can query and operate HTB directly.

Features

• MCP over stdio (works with common local MCP clients)
• Structured JSON responses from all tools
• Environment-based auth/config (no credential files required)
• API-focused actions for users, machines, challenges, VPN metadata, prolabs, seasons, badges, sherlocks, pwnbox

Requirements

• Python 3.10+
• Hack The Box App Token

Create your HTB App Token in:

• https://app.hackthebox.com/account-settings

Installation

cd /path/to/htb-mcp
python3.10 -m venv .venv
source .venv/bin/activate
pip install -e .

For development:

pip install -e ".[dev]"

Environment Variables

Required:

• HTB_APP_TOKEN: HTB App Token

Optional:

• HTB_API_BASE_URL: default https://labs.hackthebox.com/api/
• HTB_USER_AGENT: default htb-mcp/<version>
• HTB_VERIFY_SSL: true|false|1|0|yes|no (default true)
• HTB_HTTP_PROXY
• HTB_HTTPS_PROXY

MCP Configuration

Option A: installed command (htb-mcp)

{
  "mcpServers": {
    "htb": {
      "command": "htb-mcp",
      "env": {
        "HTB_APP_TOKEN": "YOUR_HTB_APP_TOKEN"
      }
    }
  }
}

Option B: run module directly from source

{
  "mcpServers": {
    "htb": {
      "command": "python3.10",
      "args": ["-m", "htb_mcp"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/htb-mcp/src",
        "HTB_APP_TOKEN": "YOUR_HTB_APP_TOKEN"
      }
    }
  }
}

Running Manually

HTB_APP_TOKEN=YOUR_HTB_APP_TOKEN htb-mcp

Response Envelope

All tool responses follow one envelope:

Success:

{
  "ok": true,
  "data": {}
}

Error:

{
  "ok": false,
  "error": {
    "type": "ErrorType",
    "message": "Human readable message",
    "details": {}
  }
}

Tool Catalog

User:

• htb_user_get
• htb_user_activity
• htb_user_respect

Machine:

• htb_machine_list
• htb_machine_get
• htb_machine_active
• htb_machine_start
• htb_machine_stop
• htb_machine_reset
• htb_machine_extend
• htb_machine_submit_flag
• htb_machine_rate_flag

Challenge:

• htb_challenge_list
• htb_challenge_search
• htb_challenge_get
• htb_challenge_submit
• htb_challenge_instance_start
• htb_challenge_instance_stop
• htb_challenge_instance_status

Prolabs and Certificates:

• htb_prolabs_list
• htb_prolabs_get
• htb_prolabs_submit
• htb_certificate_list

VPN:

• htb_vpn_servers_list
• htb_vpn_accessible_list
• htb_vpn_switch
• htb_vpn_active_connections

Pwnbox:

• htb_pwnbox_status
• htb_pwnbox_terminate

Sherlocks:

• htb_sherlock_categories
• htb_sherlock_list

Badges:

• htb_badges_list

Seasons:

• htb_season_list
• htb_season_details
• htb_season_current_machines

Development

Run tests:

PYTHONPATH=src python3.10 -m pytest -q

Quick syntax check:

PYTHONPATH=src python3.10 -m py_compile src/htb_mcp/*.py src/htb_mcp/htbapi/*.py

Project Layout

htb-mcp/
  src/htb_mcp/
    server.py
    tools.py
    config.py
    client_factory.py
    serialization.py
    htbapi/
  tests/

Notes

• This project depends on HTB API behavior and can be affected by HTB-side changes.
• Keep your HTB_APP_TOKEN secret.