HTB MCP Server
Provides live control of Hack The Box labs through the HTB Labs API, enabling AI agents to list, search and spawn machines, stop/reset/extend and submit flags, browse and submit challenges, manage VPN servers and download OVPN configs, view user profile, rank progression and recent activity, and call arbitrary HTB API endpoints directly.
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 MCP Server verify my HTB session, then spawn BoardLight and give me the IP"
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-mcp
MCP server that gives AI agents live control of Hack The Box labs — machines, challenges, flags and VPN — by wrapping the bundled, zero-dependency HTB Agent Toolkit CLI.
The server calls the HTB Labs API for your account. Directory lists are cached for one hour by default; machine and VPN status are always live. It spawns toolkit/htb.py (Python 3.10+, standard library only) with argument arrays (no shell), returns the CLI's compact JSON as structured content, and maps its structured stderr errors (config, auth, rate_limit, conflict, state, ...) onto MCP errors.
Quick start
Requirements: Node.js 22.13 or newer and Python 3.10 or newer on PATH (set HTB_PYTHON if yours is elsewhere).
Claude Code:
claude mcp add htb -- npx -y @zebbern/htbCodex CLI:
codex mcp add htb -- npx -y @zebbern/htbAny MCP client (Claude Desktop, Cursor, Kimi, etc.), config JSON — HTB_API_KEY is optional if you instead create toolkit/.env.local inside the installed package:
{
"mcpServers": {
"htb": {
"command": "npx",
"args": ["-y", "@zebbern/htb"],
"env": { "HTB_API_KEY": "your-htb-app-token-here" }
}
}
}Create an App Token at https://app.hackthebox.com/profile/settings (App Tokens section). Then call htb_doctor once to verify the session.
On Windows, use npx.cmd as the launch command if your MCP host cannot resolve npx. The wrapper forces UTF-8 for Python's stdout and stderr, including descriptions containing emoji.
As a plugin (bundles the agent skill that teaches safe, effective usage): this repo is a valid plugin for Claude Code (.claude-plugin/), Codex (.codex-plugin/) and Kimi (kimi-plugin/). Add it from your client's plugin marketplace flow pointing at zebbern/htb-mcp, or for Kimi Work use this plugin link.
Then ask things like:
"Check my HTB session and show which machine is active"
"Spawn BoardLight and give me the IP"
"Submit this flag for machine 444: HTB{...}"
"Switch my VPN to us-free-1 and download the config"
Related MCP server: htb-app-mcp
Tools at a glance
Tool | What it does |
| Session health check: API key source, whoami, active machine, VPN assignment — run it first |
| List (playable/retired/todo/unreleased/SP-tier) and ranked search over machines |
| Machine details by id or name; what's running right now (live) |
| Spawn a box; |
| Lifecycle control of the active (or named) machine |
| Submit a user/root flag; personal difficulty rating optional |
| Browse challenges in 25-row pages, search, and inspect details |
| Submit a challenge flag; uses its listed difficulty as the rating unless one is supplied |
| List usable VPN servers ( |
| Switch servers; download OVPN configs |
| Profile, rank progression, recent owns |
| Escape hatch: call any HTB API endpoint directly (v4 by default, v5 via |
Read-only tools are annotated readOnlyHint; stop, reset and both submit tools are annotated destructiveHint. Full reference: docs/tools.md.
Documentation
docs/tools.md: complete tool reference with parameters and error types
docs/architecture.md: the wrapper design (process model, timeouts, error mapping)
docs/development.md: local setup, smoke test, releasing
docs/agents.md: agent skill, MCP registry and plugin packaging
Security
Token handling: the App Token is read by the bundled Python toolkit from
HTB_API_KEY(inherited from your MCP client config) ortoolkit/.env.local. The MCP server never reads, stores, logs or prints the key — it only passes the environment through to the child process.Never commit
.env.local. It is covered by.gitignore, and by both the root.npmignoreandtoolkit/.npmignoresonpm packcannot ship it; the release workflow hard-fails if a tarball ever contains it or the.cachedirectory.No shell injection: commands are built as argument arrays and run with
execFile,shell: false— machine names, flags and raw JSON bodies are passed verbatim as argv entries.State-changing tools are annotated: read-only vs destructive hints let MCP hosts gate
stop/reset/submit. Annotations don't replace consent — the bundled agent skill instructs agents to confirm before destructive or irreversible actions.This controls your real HTB account against live labs. Use it only for your own authorized HTB activity.
Credits
HTB Agent Toolkit — the bundled CLI (MIT), vendored under
toolkit/Hack The Box — this is an unofficial client of the public Labs API, not affiliated with or endorsed by Hack The Box Ltd
Available Tools
22 toolshtb_challenge_infoHTB Challenge InfoARead-onlyIdempotent
Show a challenge by id or name (names resolve case-insensitively). Returns an info block: id, name, category, difficulty, points, stars, retired, state, solved, release, description, solves, maker. Set full=true for the raw API payload.
Inputs: target (required), full.
htb_challenge_listList HTB ChallengesARead-onlyIdempotent
List Hack The Box challenges (active by default; retired=true for retired ones). Returns compact JSON rows (id, name, category, difficulty, points, retired, state, solved, solves). Cached for 1h; noCache bypasses the cache.
Inputs: noCache, retired.
htb_challenge_searchSearch HTB ChallengesARead-onlyIdempotent
Client-side search over the (cached) challenge lists, ranked by relevance. Matches id, name, category, difficulty, points, state. Use all to also scan retired challenges. Follow up with htb_challenge_info on a candidate.
Inputs: query (required), all, limit, retired.
htb_challenge_submitSubmit Challenge FlagADestructive
Submit a challenge flag. difficulty is a required rating in steps of 10 from 10 to 100 — ask the user if they did not provide one. Submissions are irreversible: confirm with the user first.
Inputs: flag (required), target (required), difficulty (required).
htb_doctorHTB Session Health CheckARead-onlyIdempotent
Session health check: verifies API key resolution (and where the key came from), API connectivity (whoami), the currently active machine, and the VPN assignment in one call. Run this first in any session; exits with an error only when the key or API check fails. Needs HTB_API_KEY (env var or toolkit/.env.local).
Inputs: no named parameters.
htb_machine_activeActive HTB MachineARead-onlyIdempotent
Show the currently active machine: id, name, ip, os, difficulty, expires_at/expires_in, lab server. Always live, never cached. An empty info block means nothing is running. details=true adds the synopsis and linked academy modules.
Inputs: details.
htb_machine_extendExtend HTB MachineA
Extend a machine's expiry time; defaults to the currently active machine when target is omitted. Non-destructive: the running box and its state are untouched.
Inputs: target.
htb_machine_listList HTB MachinesARead-onlyIdempotent
List Hack The Box machines. Default is the playable list (page 1); use filter for retired, todo, or unreleased lists, and spTier for Seasonal/starting-point tier lists. Returns compact JSON rows (id, name, os, difficulty, points, active, spawned, free). Lists are cached for 1h; noCache bypasses the cache.
Inputs: page, filter, spTier, noCache.
htb_machine_profileHTB Machine ProfileARead-onlyIdempotent
Show a machine profile by id or name (e.g. 444 or 'BoardLight'). Returns an info block: id, name, os, difficulty, points, stars, retired, free, release, maker, user/system owns, tags. Set full=true for the complete raw API payload.
Inputs: target (required), full.
htb_machine_resetReset HTB MachineADestructive
Reset a machine to a fresh state; defaults to the currently active machine when target is omitted. Wipes the box back to its initial state — confirm with the user before calling.
Inputs: target.
htb_machine_searchSearch HTB MachinesARead-onlyIdempotent
Client-side search over the HTB machine lists, ranked by relevance. Matches id, name, OS, difficulty, tags, makers, points, IP. Use all to also scan retired machines. profiles additionally fetches every scanned machine's profile to match description text — powerful but SLOW (one API request per machine, can take minutes), use it only when list fields are not enough. Follow up with htb_machine_profile on a candidate.
Inputs: query (required), all, limit, retired, +2 more.
htb_machine_startStart HTB MachineA
Start (spawn) a machine by id or name. mode 'auto' (default) tries play then falls back to spawn. With wait=true (default) the CLI retries while spawn capacity is full, then waits for the IP — this can take several minutes at peak times; the response contains {id, name, ip, spawn}. Only one machine can be active at a time: a conflict error names the blocker, stop it (with the user's consent) and retry.
Inputs: target (required), mode, wait, interval, +1 more.
htb_machine_stopStop HTB MachineADestructive
Stop (terminate) a machine; defaults to the currently active machine when target is omitted. This kills the running box and its state — confirm with the user before calling.
Inputs: target.
htb_machine_submitSubmit Machine FlagADestructive
Submit a user or root flag for a machine (HTB infers which from the flag value). difficulty is a required rating in steps of 10 from 10 (piece of cake) to 100 (brainfuck) — ask the user if they did not provide one. Submissions are irreversible: confirm with the user first.
Inputs: flag (required), target (required), difficulty (required).
htb_rawRaw HTB API CallA
Escape hatch: call any HTB API endpoint directly. Hits the v4 base (https://labs.hackthebox.com/api/v4) by default — pass baseUrl 'https://labs.hackthebox.com/api/v5' for v5 endpoints. path like '/machine/active' (leading slash optional); data takes a raw JSON string body. Set output to save a binary response (for example, GET /challenge/download/) instead of decoding it as text. Relative output paths resolve under the toolkit directory. Use when a typed tool is missing or an endpoint moved.
Inputs: path (required), method (required), data, output, +1 more.
htb_user_activityHTB User ActivityARead-onlyIdempotent
Show recent owns (machine user/root flags and challenges), newest first. Rows: date, type (user/root/challenge), id, name, points, blood.
Inputs: limit.
htb_user_infoHTB User ProfileARead-onlyIdempotent
Show the user's HTB profile: id, name, rank, points, ranking, user/system owns, respects, country, team, vip. Set full=true for the raw profile payload.
Inputs: full.
htb_user_progressHTB Rank ProgressARead-onlyIdempotent
Show rank progression: current rank and points, next rank and its points requirement, current_rank_progress / rank_requirement (percent), rank_ownership, and own counts. Use this to answer 'how close am I to ranking up?'.
Inputs: no named parameters.
htb_vpn_downloadDownload HTB VPN ConfigARead-onlyIdempotent
Download an OVPN config file for a server (id, alias, or live name). Default output is lab-vpn.ovpn in the toolkit directory; variant 0 = UDP. The toolkit does NOT run OpenVPN — the user connects themselves with the downloaded file.
Inputs: server (required), output, variant.
htb_vpn_serversList HTB VPN ServersARead-onlyIdempotent
List the VPN servers the account can use, live (includes VIP/VIP+/dedicated pools), assigned server first. Rows: id, name, group, location, clients, full, assigned. Default product pool is 'labs'. static=true shows only the built-in offline alias table and needs NO API key.
Inputs: static, product.
htb_vpn_statusHTB VPN StatusARead-onlyIdempotent
Show the VPN server currently assigned to the account: id, name, location, product — or assigned=false when none.
Inputs: product.
htb_vpn_switchSwitch HTB VPN ServerA
Switch the account to a different VPN server. Accepts a numeric id (289), a static alias (us-free-1, eu-sp-1, ...) or a live name from htb_vpn_servers (e.g. 'EU Machines VIP+ 1'). Affects the user's whole HTB connection — mention it before switching.
Inputs: server (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Most tools target a clearly distinct resource+action (machine_start vs machine_stop vs machine_reset vs machine_extend, vpn_servers vs vpn_status vs vpn_switch vs vpn_download). A few near-neighbors exist (machine_list vs machine_search, challenge_list vs challenge_search, machine_active vs machine_profile), but the descriptions explicitly differentiate scope and use cases, so an agent can reliably pick the right one.
Every tool uses the same `htb_<resource>_<action>` snake_case pattern (htb_machine_start, htb_challenge_submit, htb_vpn_switch, htb_user_info). The two outliers (htb_doctor, htb_raw) still follow the consistent lowercase htb_ prefix and read as intentional singletons.
22 tools is on the heavy side, but the server spans genuinely distinct sub-domains (machines, challenges, VPN, user profile, session health, raw escape hatch), and each tool covers a real operation. There is little obvious redundancy, so the count is justified by the broad surface rather than bloated.
The set covers the full lifecycle: machine list/search/profile/start/stop/reset/extend/submit, challenge list/search/info/submit, VPN list/status/switch/download, user info/progress/activity, plus a health check and htb_raw escape hatch for anything missing. No obvious dead ends for the HTB domain.
Maintenance
Related MCP Connectors
Let your AI agent operate any website through a real, logged-in browser session.
Operate GitHub from your AI assistant: repos, PRs, issues, Actions. Previews and read-only mode.
Real Linux labs your AI agent deploys, routes and runs, with domains, TLS, DBs and an audit log.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to execute penetration testing commands and security tools on Kali Linux remotely. Supports automated reconnaissance, vulnerability scanning, and CTF solving through integration with 25+ offensive security tools like nmap, gobuster, and nuclei.16-
- AlicenseCqualityDmaintenanceEnables interaction with Hack The Box App services including machines, challenges, sherlocks, and more through the HTB API v4.601MIT
- 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
- AlicenseAqualityCmaintenanceEnables AI agents to interact with the FlagForge REST API, allowing them to search solved CTF challenges, work on live event challenges, record evidence, submit flag candidates, and write markdown writeups.19ISC