htb

The HackTheBox MCP Server (HTB MCP) provides programmatic access to HackTheBox platform functionality via the Model Context Protocol (MCP). It exposes 12 tools across three major areas: Challenge Management, Machine Management, and User/Utility operations. Through the MCP interface, you can list challenges and machines, start environments, submit flags, retrieve user profiles and progress, and perform advanced searches. The server communicates using MCP’s standard JSON-RPC 2.0 over stdio, and it integrates with the HTB API v4 using your provided JWT token. To connect, you typically run the server locally or in a container and point your MCP client to the server executable, providing the HTB token in the environment or configuration. The included integration example shows how to wire the HTB token into the MCP client configuration so the server can authenticate with HackTheBox on your behalf.

Once connected, you can invoke tools like list_challenges, start_challenge, submit_challenge_flag, list_machines, start_machine, get_machine_ip, submit_user_flag, submit_root_flag, get_user_profile, get_user_progress, search_content, and get_server_status. Each tool corresponds to a specific HTB action (e.g., listing challenges with filters, starting a machine, or submitting flags). The server’s design encourages reuse of common tool patterns, and you can extend it by implementing new Tool types and registering them in the tool registry.

Prerequisites:

• Go 1.21 or later
• A HackTheBox account with API access and a valid JWT token
• Internet access for dependencies and HTB API calls

Installation steps:

1. Clone the repository:

git clone https://github.com/NoASLR/htb-mcp-server.git
cd htb-mcp-server

2. Build the binary:

go build -o htb-mcp-server main.go

3. Obtain your HTB token as described in the README (Profile Settings -> App Token) and export it:

export HTB_TOKEN="your.jwt.token.here"

4. Run the server in standalone mode:

./htb-mcp-server

Optional: Run with Docker (if you prefer containerized deployment), using the token environment variable inside the container:

# Build the Docker image (requires Dockerfile in repo)
docker build -t htb-mcp-server .

# Run the container with the token
docker run -e HTB_TOKEN="your.jwt.token.here" -p 3000:3000 htb-mcp-server

5. If you plan to run in MCP client mode, configure your client with the provided HTB token integration example from the README.

Tips and common considerations:

• Keep your HTB_TOKEN secure; never commit it to version control.
• Adjust server behavior using environment variables described in the README (SERVER_PORT, LOG_LEVEL, RATE_LIMIT_PER_MINUTE, CACHE_TTL_SECONDS, REQUEST_TIMEOUT_SECONDS).
• If you encounter token errors, verify token validity and permissions in HackTheBox profile settings.
• The MCP transport is JSON-RPC 2.0 over stdio in this server, but the example usage shows how you’d wire it in an MCP client configuration (e.g., Claude Desktop).
• For production, consider enabling debug logging temporarily to diagnose issues, and ensure your network can reach labs.hackthebox.com endpoints for API calls.