Skip to main content
Glama

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/htb

Codex CLI:

codex mcp add htb -- npx -y @zebbern/htb

Any 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

htb_doctor

Session health check: API key source, whoami, active machine, VPN assignment — run it first

htb_machine_list / htb_machine_search

List (playable/retired/todo/unreleased/SP-tier) and ranked search over machines

htb_machine_profile / htb_machine_active

Machine details by id or name; what's running right now (live)

htb_machine_start

Spawn a box; wait=true retries full spawn servers and returns the IP

htb_machine_stop / htb_machine_reset / htb_machine_extend

Lifecycle control of the active (or named) machine

htb_machine_submit

Submit a user/root flag; personal difficulty rating optional

htb_challenge_list / htb_challenge_search / htb_challenge_info

Browse challenges in 25-row pages, search, and inspect details

htb_challenge_submit

Submit a challenge flag; uses its listed difficulty as the rating unless one is supplied

htb_vpn_servers / htb_vpn_status

List usable VPN servers (static=true works with no API key); current assignment

htb_vpn_switch / htb_vpn_download

Switch servers; download OVPN configs

htb_user_info / htb_user_progress / htb_user_activity

Profile, rank progression, recent owns

htb_raw

Escape hatch: call any HTB API endpoint directly (v4 by default, v5 via baseUrl); output saves binary responses such as challenge archives

Read-only tools are annotated readOnlyHint; stop, reset and both submit tools are annotated destructiveHint. Full reference: docs/tools.md.

Documentation

Security

  • Token handling: the App Token is read by the bundled Python toolkit from HTB_API_KEY (inherited from your MCP client config) or toolkit/.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 .npmignore and toolkit/.npmignore so npm pack cannot ship it; the release workflow hard-fails if a tarball ever contains it or the .cache directory.

  • 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

Available Tools

22 tools
htb_challenge_infoHTB Challenge InfoA
Read-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 ChallengesA
Read-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_submitSubmit Challenge FlagA
Destructive

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 CheckA
Read-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 MachineA
Read-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 MachinesA
Read-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 ProfileA
Read-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 MachineA
Destructive

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_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 MachineA
Destructive

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 FlagA
Destructive

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 ActivityA
Read-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 ProfileA
Read-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 ProgressA
Read-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 ConfigA
Read-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 ServersA
Read-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 StatusA
Read-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

    A4.1/5.0

    Scored across 22 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      19
      ISC