HTB

Provides access to HackTheBox data and actions via MCP tools for challenges, machines, users, and search.

go

2

GitHub Stars

go

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "noaslr-htb-mcp-server": {
      "command": "/path/to/htb-mcp-server",
      "args": [],
      "env": {
        "HTB_TOKEN": "your.jwt.token.here"
      }
    }
  }
}

You can run the HackTheBox MCP Server to give AI assistants programmatic access to HackTheBox functionality. It exposes a set of tools for challenges, machines, user data, and search utilities, all mediated through a standard MCP interface. This server helps automate workflows, research, and integration with your AI workflows while respecting HTB API access.

How to use

To use the HTB MCP Server, you run the server locally and connect your MCP client to it. The server exposes a variety of tools that your AI assistant can call to list challenges, manage machines, fetch user data, and perform searches. You provide your HTB API token so the server can authenticate with HackTheBox and perform the requested actions on your behalf.

Typical usage patterns include starting a machine and retrieving its connection details, listing active challenges, submitting flags for challenges or machines, and searching for content across challenges and machines. You can also check the current health and status of the MCP server to ensure reliable operation.

How to install

Prerequisites: you need Go 1.21 or later and a valid HackTheBox account with API access. You will also need an HTB API token in JWT format.

Step-by-step installation and run flow:

Clone the project, build the binary, and run it with your token.

Additional configuration and notes

Environment variables: you must provide HTB_TOKEN with your HackTheBox API token. You can set optional runtime parameters such as SERVER_PORT, LOG_LEVEL, RATE_LIMIT_PER_MINUTE, CACHE_TTL_SECONDS, and REQUEST_TIMEOUT_SECONDS to customize behavior.

Running in standalone mode, you start the server after exporting your token. For example, you can run the server directly in your shell or through a container, ensuring the token is supplied to the process.

MCP client integration: configure your MCP client to point to the local server and pass HTB_TOKEN through the environment so the client can authenticate when calling tools.

Security considerations: never commit your HTB token to version control, and enforce rate limiting, input validation, and careful error handling to avoid exposing sensitive information.

Health and troubleshooting: monitor the server status and logs. If you encounter token errors or connectivity issues to HackTheBox, verify token validity and network access to the API endpoints.

Available tools

list_challenges

Get a paginated list of challenges with filtering capabilities to refine results by category, difficulty, or status.

start_challenge

Initialize a challenge environment so you can begin working on it within a managed session.

submit_challenge_flag

Submit a challenge flag for verification and receive result feedback.

list_machines

Retrieve active and retired machines along with their status information.

start_machine

Launch a machine and obtain connection details such as IP, port, and access method.

get_machine_ip

Fetch the IP address of an active machine.

submit_user_flag

Submit a user flag for a machine to verify capture.

submit_root_flag

Submit a root flag for a machine to verify full compromise.

get_user_profile

Retrieve the user profile and statistics from HackTheBox.

get_user_progress

Get completion status and achievements for the current user.

search_content

Perform an advanced search across challenges, machines, and users for quick discovery.

get_server_status

Provide a health check and general server information.