htb-app-mcp
This server acts as a local MCP proxy for Hack The Box (HTB) App services, providing a unified interface to interact with machines, challenges, Sherlocks, fortresses, seasonal content, Starting Point, and Pro Labs.
Account & VPN Management: Retrieve your profile, check VPN connection, list and switch VPN servers, and download OpenVPN profiles.
Search & API Access: Search HTB content (machines, challenges, users, teams) and make direct GET/POST requests to the HTB API.
Machines: List/filter machines, get details, view active machines, tasks, and recommended machines; spawn, stop, extend, reset, and submit flags.
Challenges: List/filter challenges, get info, categories, download files, start/stop containers, and submit flags.
Sherlocks (DFIR): List, get info, tasks, progress; start/stop/reset VMs; download files; submit task flags.
Fortresses: List, get info, flags; submit flags; vote to reset.
Seasonal Content: List seasons, get active machine, machines, rewards, ranks, and leaderboards.
Starting Point: Track tier progress, get tier metadata, submit machine task answers.
Pro Labs: List labs, overviews, machines, flags; submit flags.
Downloads: OVPN profiles, challenge/sherlock ZIPs with auto-extraction, password support, and rate limiting.
Provides integration with Hack The Box's API v4 for managing machines, challenges, sherlocks, fortresses, seasonal content, starting point, pro labs, VPN connections, and user account information.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@htb-app-mcp list currently active machines"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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/v4This 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.envneeded.Fallback: stdio +
.env/ environment variables.Exposed tools: 60 (plus the
htb://service-mapresource).
Related MCP server: htb-mcp
Setup
Prerequisites:
Python 3.11+
uvHTB App Token from
app.hackthebox.com
Install dependencies:
uv syncRecommended mode: HTTP with Authorization header
Start the server:
uv run htb-app-mcp --transport http --host 127.0.0.1 --port 8000Configure 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 8000and 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-httpAlternative 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 |
|
VPN |
|
Search |
|
Machines |
|
Machine actions |
|
Challenges |
|
Challenge actions |
|
Sherlocks |
|
Fortresses |
|
Seasonal |
|
Starting Point |
|
Pro Labs |
|
Resource:
htb://service-mapPrompt:
htb_target_workflowHTB 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}/flagSome older endpoints documented online now return 404 (e.g. /machine/list, /machines, /starting-point/machines).
Downloads
Supported downloads:
OVPN:
htb_download_ovpnChallenge ZIP:
htb_download_challengeSherlock ZIP:
htb_download_sherlock
Defaults:
directory:
downloadsZIP password:
hacktheboxZIP 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 --helpMain 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 5Local validation
Smoke test with direct client:
uv run python tests/smoke_client.pySmoke test with MCP stdio:
uv run python tests/smoke_mcp.pySmoke test with MCP HTTP and Authorization header:
uv run python tests/smoke_http.pyTroubleshooting
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 8000If 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 httpthe MCP config points to
http://127.0.0.1:8000/mcpHTB_MCP_PATHor--pathis 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->easyVery Easy->very-easyunsolved->incompletedsolved->completesort_by=difficulty->user_difficultyfor challengestarget_type=challenge->challengesfor 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.0Logs with signed URLs
HTTPX and httpcore logs are silenced by default to avoid printing temporary S3 URLs. For debugging:
export HTB_MCP_VERBOSE_HTTP=1Do not share verbose logs: they may contain temporary presigned URLs.
Security
Keep the HTTP server on loopback (
127.0.0.1).Do not commit
.envor tokens.Do not paste tokens in logs or the README.
Avoid
HTB_MCP_VERBOSE_HTTP=1outside local debugging.Tools like
spawn,stop,reset,submit flag,switch VPNhave 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 toolshtb_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_recommended_machinesB
Return HTB recommended machine cards.
Inputs: no named parameters.
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_searchB
Search HTB content. target_type can be all, machines, challenges, users, or teams.
Inputs: query (required), limit, target_type.
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
Scored across 60 tools
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.
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.
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.
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
Related MCP Connectors
Manage SiteGPT chatbots and account resources through the SiteGPT API v2.
Analyze authorized assets and read security findings through your Hackaiz account.
Grade a page's HTTP security headers, search penetration testing guides and send a pentest request for a person. The read tools need no authentication; request_pentest needs a free agent key.
Manage a Vajro store through the Hermes API: themes, blocks, settings, plugins and more.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables 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 npmISC
- AlicenseNot gradedqualityDmaintenanceEnables assistants to interact with Hack The Box by wrapping HTB API operations as MCP tools for querying and operating HTB resources.1GPL 3.0
- AlicenseBqualityDmaintenanceProvides 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.53MIT
- FlicenseBqualityBmaintenanceEnables 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.251-