Skip to main content
Glama

HTB App MCP

Local MCP server for Hack The Box App services via the HTB API (primarily v4, with machine flag submission on v5) at:

https://labs.hackthebox.com/api/v4

This project does not use pyhackthebox: the client talks directly to HTB via httpx and authenticates with:

Authorization: Bearer <HTB_APP_TOKEN>

Do not confuse this with the official HTB CTF MCP at mcp.hackthebox.ai/v1/ctf/mcp/. This server is for HTB App/Labs content: Machines, Challenges, Sherlocks, Fortresses, Starting Point, Seasonal, and Pro Labs.

Current status

  • Recommended transport: local Streamable HTTP MCP on http://127.0.0.1:8000/mcp.

  • HTTP is stateless by default: restart the server without your MCP client getting stuck on Session not found.

  • Recommended auth: MCP header Authorization: Bearer <HTB_APP_TOKEN>, no .env needed.

  • Fallback: stdio + .env / environment variables.

  • Exposed tools: 60 (plus the htb://service-map resource).

Related MCP server: htb-mcp

Setup

Prerequisites:

  • Python 3.11+

  • uv

  • HTB App Token from app.hackthebox.com

Install dependencies:

uv sync

Start the server:

uv run htb-app-mcp --transport http --host 127.0.0.1 --port 8000

Configure your MCP client:

{
  "mcpServers": {
    "htb-app-mcp": {
      "url": "http://127.0.0.1:8000/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer <HTB_APP_TOKEN>"
      }
    }
  }
}

In this mode the token comes from the MCP client and is forwarded to HTB only. No .env required.

Restarting the server

HTTP is stateless by default, avoiding the Session not found issue. You can restart:

uv run htb-app-mcp --transport http --host 127.0.0.1 --port 8000

and the MCP client can reconnect without starting a new chat. If the client still uses an old connection, reload the MCP servers on the client side.

For protocol debugging you can force stateful mode:

uv run htb-app-mcp --transport http --stateful-http

Alternative mode: stdio

Stdio is useful when an MCP host wants to launch the local process directly.

Config:

{
  "mcpServers": {
    "htb-app-mcp": {
      "command": "uv",
      "args": ["--directory", "D:\\Sources\\htb-app-mcp", "run", "htb-app-mcp"],
      "env": {
        "HTB_API_TOKEN": "<HTB_APP_TOKEN>"
      }
    }
  }
}

You can also use .env as a local fallback:

cp .env.example .env
# edit .env and set HTB_API_TOKEN (or API_TOKEN)
uv run htb-app-mcp

.env is gitignored.

Tools

Area

Tools

Account

htb_whoami, htb_user_profile

VPN

htb_connection_status, htb_vpn_servers, htb_switch_vpn_server, htb_download_ovpn

Search

htb_search, htb_api_get, htb_api_post

Machines

htb_list_machines, htb_machine_info, htb_active_machine, htb_active_virtual_machine, htb_recommended_machines, htb_machine_tasks

Machine actions

htb_spawn_machine, htb_stop_machine, htb_extend_machine, htb_reset_machine, htb_submit_machine_flag

Challenges

htb_list_challenges, htb_challenge_info, htb_challenge_categories, htb_download_challenge

Challenge actions

htb_start_challenge, htb_stop_challenge, htb_start_container, htb_stop_container, htb_submit_challenge_flag

Sherlocks

htb_list_sherlocks, htb_sherlock_info, htb_sherlock_tasks, htb_sherlock_progress, htb_sherlock_play, htb_start_sherlock_vm, htb_stop_sherlock_vm, htb_reset_sherlock_vm, htb_download_sherlock, htb_submit_sherlock_task_flag

Fortresses

htb_list_fortresses, htb_fortress_info, htb_fortress_flags, htb_submit_fortress_flag, htb_reset_fortress

Seasonal

htb_list_seasons, htb_active_season_machine, htb_season_machines, htb_season_rewards, htb_season_user_rank, htb_season_user_ranks, htb_season_leaderboard, htb_season_top_leaderboard

Starting Point

htb_starting_point_progress, htb_starting_point_tier, htb_submit_machine_task

Pro Labs

htb_list_prolabs, htb_prolab_overview, htb_prolab_machines, htb_prolab_flags, htb_submit_prolab_flag

Resource:

htb://service-map

Prompt:

htb_target_workflow

HTB endpoints covered

The server uses verified real endpoints on labs.hackthebox.com/api/v4 (with machine flag submission on api/v5), including:

GET  /user/info
GET  /connection/status
GET  /user/connection/status
GET  /connections/servers?product=...
POST /connections/servers/switch/{vpnId}
GET  /access/ovpnfile/{vpnId}/0
GET  /access/ovpnfile/{vpnId}/0/1

GET  /search/fetch

GET  /machine/paginated
GET  /machine/profile/{machineSlug}
GET  /machine/active
GET  /api/v5/virtual_machine/active
GET  /machine/recommended
GET  /machines/{machineId}/tasks
POST /vm/spawn
POST /vm/terminate
POST /vm/extend
POST /vm/reset
POST /vm/reset/vote
POST /vm/reset/vote/accept
POST /api/v5/machine/own

GET  /challenges
GET  /challenge/info/{challengeSlug}
GET  /challenge/categories/list
GET  /challenges/{challengeId}/download_link
POST /container/start
POST /container/stop
POST /challenge/own

GET  /sherlocks
GET  /sherlocks/{sherlockId}/info
GET  /sherlocks/{sherlockId}/tasks
GET  /sherlocks/{sherlockId}/progress
GET  /sherlocks/{sherlockId}/play
POST /challenge/start/vm/{sherlockId}
POST /challenge/reset/vm/{sherlockId}
GET  /sherlocks/{sherlockId}/download_link
POST /sherlocks/{sherlockId}/tasks/{taskId}/flag

GET  /fortresses
GET  /fortress/{fortressId}
GET  /fortress/{fortressId}/flags
POST /fortress/{fortressId}/flag
POST /fortress/{fortressId}/reset

GET  /season/list
GET  /season/machine/active
GET  /season/machines/{seasonId}
GET  /season/rewards/{seasonId}
GET  /season/user/rank/{seasonId}
GET  /season/user/{userId}/ranks
GET  /season/{players|teams}/leaderboard
GET  /season/{players|teams}/leaderboard/top/{seasonId}

GET  /sp/tiers/progress

GET  /prolabs
GET  /prolab/{prolabId}/overview
GET  /prolab/{prolabId}/machines
GET  /prolab/{prolabId}/flags
POST /prolab/{prolabId}/flag

Some older endpoints documented online now return 404 (e.g. /machine/list, /machines, /starting-point/machines).

Downloads

Supported downloads:

  • OVPN: htb_download_ovpn

  • Challenge ZIP: htb_download_challenge

  • Sherlock ZIP: htb_download_sherlock

Defaults:

  • directory: downloads

  • ZIP password: hackthebox

  • ZIP extraction: enabled for challenges and Sherlocks

  • ZIP downloads serialized with a minimum interval to reduce 429 Too Many Requests

Change the directory:

export HTB_DOWNLOAD_DIR="D:/Sources/htb-app-mcp/downloads"

Environment variables

| Variable | Default | Usage | |---|---|---:|---| | HTB_API_TOKEN | empty | HTB token for stdio or HTTP fallback | | API_TOKEN | empty | Supported alias for compatibility | | HTB_TOKEN | empty | Supported alias | | HTB_API_BASE_URL | https://labs.hackthebox.com/api/v4 | Override base API URL | | HTB_DOWNLOAD_DIR | downloads | Download directory | | HTB_CLEANUP_DOWNLOADS_ON_EXIT | 1 | Wipe download dir contents on shutdown; 0 to keep | | HTB_MAX_RETRIES | 3 | Retries for transient HTTP failures (429/5xx, connect errors) | | HTB_RETRY_BACKOFF | 0.5 | Base seconds for exponential backoff + jitter | | HTB_RETRY_BACKOFF_MAX | 20 | Cap for a single backoff wait (seconds) | | HTB_TIMEOUT | 30 | HTTP timeout to HTB in seconds | | HTB_LOAD_DOTENV | 1 | Set to 0 to disable .env loading | | HTB_MCP_TRANSPORT | stdio | stdio, http, streamable-http | | HTB_MCP_HOST | 127.0.0.1 | HTTP bind address | | HTB_MCP_PORT | 8000 | HTTP port | | HTB_MCP_PATH | /mcp | MCP HTTP path | | HTB_MCP_STATELESS_HTTP | 1 in HTTP mode | HTTP stateless by default | | HTB_MCP_JSON_RESPONSE | 0 | Return JSON responses where supported | | HTB_MCP_LOG_LEVEL | INFO | Server log level | | HTB_MCP_VERBOSE_HTTP | 0 | Set to 1 to re-enable verbose HTTPX logging | | HTB_DOWNLOAD_MIN_INTERVAL | 1.0 | Minimum seconds between ZIP downloads | | HTB_MCP_GRACEFUL_SHUTDOWN_TIMEOUT | 5 | Graceful shutdown timeout in seconds | | HTB_MCP_WINDOWS_SELECTOR_EVENT_LOOP | 1 | Use selector event loop on Windows |

CLI

uv run htb-app-mcp --help

Main options:

--transport {stdio,http,streamable-http}
--host 127.0.0.1
--port 8000
--path /mcp
--stateless-http
--stateful-http
--json-response
--log-level INFO
--graceful-shutdown-timeout 5

Local validation

Smoke test with direct client:

uv run python tests/smoke_client.py

Smoke test with MCP stdio:

uv run python tests/smoke_mcp.py

Smoke test with MCP HTTP and Authorization header:

uv run python tests/smoke_http.py

Troubleshooting

Session not found

Update the code and restart in default HTTP stateless mode:

uv run htb-app-mcp --transport http --host 127.0.0.1 --port 8000

If the client still holds an old connection, use reload MCP servers on the client side.

404 Not Found on /mcp

Check that:

  • the server is started with --transport http

  • the MCP config points to http://127.0.0.1:8000/mcp

  • HTB_MCP_PATH or --path is not set to something other than /mcp

ConnectionResetError [WinError 10054] on Windows

The HTTP transport forces the selector event loop on Windows to avoid noisy stack traces when an MCP client closes a completed HTTP/SSE connection.

Traceback or ASGI callable returned without completing response on Ctrl+C

Shutdown handling is cross-platform: on Linux/macOS it uses standard Uvicorn signal handling; on Windows it enables the selector event loop only to avoid Proactor-specific noise. In all cases the server filters benign noise from Uvicorn/Starlette when closing HTTP MCP streams with Ctrl+C. For full debug logs, set HTB_MCP_VERBOSE_HTTP=1.

422 Unprocessable Entity

HTB rejects invalid parameters. The server normalizes common cases:

  • Easy -> easy

  • Very Easy -> very-easy

  • unsolved -> incompleted

  • solved -> complete

  • sort_by=difficulty -> user_difficulty for challenges

  • target_type=challenge -> challenges for search

If HTB changes the schema, use htb_api_get to test a read-only endpoint.

403 Forbidden during download

This is not necessarily a bug: HTB may deny access to challenges or files not available for your account plan, tier, status, or permissions.

429 Too Many Requests

You hit the HTB rate limit. The server serializes ZIP downloads, but if an agent requests many consecutive downloads, wait a few minutes or increase:

export HTB_DOWNLOAD_MIN_INTERVAL=2.0

Logs with signed URLs

HTTPX and httpcore logs are silenced by default to avoid printing temporary S3 URLs. For debugging:

export HTB_MCP_VERBOSE_HTTP=1

Do not share verbose logs: they may contain temporary presigned URLs.

Security

  • Keep the HTTP server on loopback (127.0.0.1).

  • Do not commit .env or tokens.

  • Do not paste tokens in logs or the README.

  • Avoid HTB_MCP_VERBOSE_HTTP=1 outside local debugging.

  • Tools like spawn, stop, reset, submit flag, switch VPN have side effects on your HTB account.

API notes

HTB App v4 APIs are not officially stable for external integrations. Most public references are community-maintained or reverse-engineered; HTB may change paths, payloads, or permissions without notice.

Available Tools

60 tools
htb_active_machineA

Return the currently active spawned machine, if one exists.

Inputs: no named parameters.

htb_active_season_machineB

Return the currently active seasonal machine card.

Inputs: no named parameters.

htb_active_virtual_machineB

Return the active machine or Sherlock VM, if one exists.

Inputs: no named parameters.

htb_api_getA

Call a read-only HTB API path for endpoint discovery. Example path: /machine/recommended.

Defaults to API v4. Prefix the path with /api/vN (e.g. /api/v5/...) to target another version.

Inputs: path (required), params_json.

htb_api_postA

Call a write HTB API path for endpoint discovery or ad-hoc mutations.

Defaults to API v4. Prefix the path with /api/vN to target another version. Example: path=/api/v5/machine/own body_json={"id":395,"flag":"abc"}

Inputs: path (required), body_json.

htb_challenge_categoriesB

List challenge categories and ids useful for filtering.

Inputs: no named parameters.

htb_challenge_infoC

Return challenge details by id or slug/name.

Inputs: challenge (required).

htb_connection_statusB

Return active HTB VPN/lab connections for the authenticated account.

Inputs: include_legacy.

htb_download_challengeB

Download a challenge ZIP by id and optionally extract it under the download directory.

Inputs: challenge_id (required), extract, password, overwrite.

htb_download_ovpnC

Download an OpenVPN profile for a VPN server id. protocol must be udp or tcp.

Inputs: vpn_id (required), filename, protocol, overwrite.

htb_download_sherlockC

Download a Sherlock ZIP by id and optionally extract it under the download directory.

Inputs: sherlock_id (required), extract, password, overwrite.

htb_extend_machineB

Extend the running time for a spawned machine VM by id.

Inputs: machine_id (required).

htb_fortress_flagsB

List flag metadata for a fortress id.

Inputs: fortress_id (required).

htb_fortress_infoC

Return details for a fortress id.

Inputs: fortress_id (required).

htb_list_challengesC

List challenges. difficulty/status accept friendly aliases; category accepts comma-separated ids.

Inputs: page, todo, state, status, +6 more.

htb_list_fortressesB

List HTB fortresses.

Inputs: no named parameters.

htb_list_machinesC

List machines with optional filters. difficulty/state accept comma-separated values.

Inputs: page, todo, state, status, +5 more.

htb_list_prolabsA

List all HTB Pro Labs with id, name, version, and subscription state.

Inputs: no named parameters.

htb_list_seasonsA

List HTB seasonal machine seasons and their active/ended state.

Inputs: no named parameters.

htb_list_sherlocksC

List Sherlocks with optional filters. category accepts comma-separated ids.

Inputs: page, state, status, keyword, +5 more.

htb_machine_infoB

Return details for a machine by id or slug/name.

Inputs: machine (required).

htb_machine_tasksC

Return task/adventure questions for a machine when available.

Inputs: machine_id (required).

htb_prolab_flagsC

List flags for a Pro Lab by id.

Inputs: prolab_id (required).

htb_prolab_machinesC

List machines in a Pro Lab by id.

Inputs: prolab_id (required).

htb_prolab_overviewB

Return detailed overview for a Pro Lab id (machines count, flags count, social links).

Inputs: prolab_id (required).

htb_reset_fortressC

Vote to reset a fortress instance.

Inputs: fortress_id (required).

htb_reset_machineC

Reset a machine VM. mode: request, vote, or accept_vote.

Inputs: machine_id (required), mode.

htb_reset_sherlock_vmC

Reset a Sherlock VM play instance by Sherlock id.

Inputs: sherlock_id (required).

htb_season_leaderboardC

Return a seasonal leaderboard. leaderboard must be players or teams.

Inputs: season_id, leaderboard.

htb_season_machinesA

List machines for a season id returned by htb_list_seasons.

Inputs: season_id (required).

htb_season_rewardsB

List rewards and rank progression data for a season id.

Inputs: season_id (required).

htb_season_top_leaderboardC

Return top seasonal leaderboard entries. period: 1Y, 6M, 3M, 1M, or 1W.

Inputs: season_id (required), period, leaderboard.

htb_season_user_rankB

Return the authenticated user's rank/progress for a season id.

Inputs: season_id (required).

htb_season_user_ranksB

Return all seasonal ranks for a specific HTB user id.

Inputs: user_id (required).

htb_sherlock_infoB

Return Sherlock details by id or slug/name.

Inputs: sherlock (required).

htb_sherlock_playC

Return Sherlock play metadata and current VM/container state.

Inputs: sherlock_id (required).

htb_sherlock_progressB

Return progress for a Sherlock id.

Inputs: sherlock_id (required).

htb_sherlock_tasksB

Return tasks/questions for a Sherlock id.

Inputs: sherlock_id (required).

htb_spawn_machineC

Spawn a machine or Starting Point VM by id.

Inputs: machine_id (required).

htb_start_challengeB

Start a challenge container by challenge id when the challenge supports containers.

Inputs: challenge_id (required).

htb_start_containerC

Start a container by container id for HTB content that exposes one.

Inputs: container_id (required).

htb_starting_point_progressA

Return Starting Point tier progress for the authenticated account.

Inputs: no named parameters.

htb_starting_point_tierA

Return metadata for a Starting Point tier id.

HTB removed the per-tier machine listing endpoint, so only tier metadata (name, description, completion) is returned. Use htb_search or htb_list_machines + htb_machine_info for Starting Point machine details.

Inputs: tier_id (required).

htb_start_sherlock_vmC

Start a Sherlock VM play instance by Sherlock id.

Inputs: sherlock_id (required).

htb_stop_challengeB

Stop a challenge container by challenge id.

Inputs: challenge_id (required).

htb_stop_containerC

Stop a container by container id for HTB content that exposes one.

Inputs: container_id (required).

htb_stop_machineC

Terminate a spawned machine or Starting Point VM by id.

Inputs: machine_id (required).

htb_stop_sherlock_vmC

Stop a Sherlock VM play instance by Sherlock id.

Inputs: sherlock_id (required).

htb_submit_challenge_flagD

Submit a challenge flag.

Inputs: flag (required), challenge_id (required).

htb_submit_fortress_flagD

Submit a fortress flag.

Inputs: flag (required), fortress_id (required).

htb_submit_machine_flagC

Submit a user/root machine flag for a machine id.

Inputs: flag (required), machine_id (required), difficulty.

htb_submit_machine_taskA

Submit the text answer/flag for a Starting Point machine task.

Use htb_machine_tasks to list available tasks and their ids for a machine. Returns 'Task flag owned!' on success.

Inputs: flag (required), task_id (required), machine_id (required).

htb_submit_prolab_flagC

Submit a flag for a Pro Lab by id.

Inputs: flag (required), prolab_id (required).

htb_submit_sherlock_task_flagB

Submit the flag/answer for a Sherlock task id.

Inputs: flag (required), task_id (required), sherlock_id (required).

htb_switch_vpn_serverA

Switch the assigned HTB VPN server to a server id returned by htb_vpn_servers.

Inputs: vpn_id (required).

htb_user_profileB

Return public profile details for an HTB user id.

Inputs: user_id (required).

htb_vpn_serversA

List VPN servers for product: labs, starting_point, fortresses, or competitive.

Inputs: product.

htb_whoamiA

Validate the API token and return the authenticated HTB account profile.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 60 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes targeting specific HTB resources (machines, challenges, sherlocks, etc.). However, there is some potential confusion between 'htb_active_machine' and 'htb_active_virtual_machine', and the generic API tools ('htb_api_get', 'htb_api_post') could overlap with other specific tools.

    Naming Consistency5/5

    All tool names follow a consistent 'htb_<verb>_<resource>' pattern in snake_case with imperative verbs. The naming is predictable and easy to understand across the entire set of 60 tools.

    Tool Count2/5

    With 60 tools, the count is well above the typical 3-15 range and falls into 'too many' per the calibration guidelines. While the server covers a broad platform, the number of tools could be streamlined by merging overlapping functions and reducing redundancy.

    Completeness5/5

    The tool set provides comprehensive coverage of HTB's features including user profile, VPN, machines, fortresses, seasons, starting point, Pro Labs, challenges, sherlocks, and search. The inclusion of generic API tools ('htb_api_get', 'htb_api_post') fills any remaining gaps, making the surface effectively complete.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables interaction with the Hevy fitness tracking platform through their API. Supports managing workouts, routines, exercise templates, and webhook subscriptions for comprehensive fitness data management.
      10 npm
      ISC
    • A
      license
      B
      quality
      D
      maintenance
      Provides programmatic access to all Scoring Engine API functionality for managing Red/White/Blue team cybersecurity competitions, including scoreboard, overview, team management, service management, injects, notifications, and admin tools.
      53
      MIT
    • F
      license
      B
      quality
      B
      maintenance
      Enables MCP-capable clients to interact with a self-hosted Homebox inventory instance, covering read and write operations for items, locations, labels, notifiers, maintenance, attachments, users, settings, statistics, bulk actions, QR codes, and CSV import/export.
      25
      1
      -