# htb-mcp

[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](#requirements)
[![License](https://img.shields.io/badge/license-GPL--3.0-green.svg)](./pyproject.toml)
[![MCP](https://img.shields.io/badge/transport-stdio-orange.svg)](#mcp-configuration)

`htb-mcp` is an MCP server for Hack The Box.  
It wraps HTB API operations as MCP tools so assistants can query and operate HTB directly.

## Features

- MCP over `stdio` (works with common local MCP clients)
- Structured JSON responses from all tools
- Environment-based auth/config (no credential files required)
- API-focused actions for users, machines, challenges, VPN metadata, prolabs, seasons, badges, sherlocks, pwnbox

## Requirements

- Python `3.10+`
- Hack The Box App Token

Create your HTB App Token in:
- `https://app.hackthebox.com/account-settings`

## Installation

```bash
cd /path/to/htb-mcp
python3.10 -m venv .venv
source .venv/bin/activate
pip install -e .
```

For development:

```bash
pip install -e ".[dev]"
```

## Environment Variables

Required:

- `HTB_APP_TOKEN`: HTB App Token

Optional:

- `HTB_API_BASE_URL`: default `https://labs.hackthebox.com/api/`
- `HTB_USER_AGENT`: default `htb-mcp/<version>`
- `HTB_VERIFY_SSL`: `true|false|1|0|yes|no` (default `true`)
- `HTB_HTTP_PROXY`
- `HTB_HTTPS_PROXY`

## MCP Configuration

### Option A: installed command (`htb-mcp`)

```json
{
  "mcpServers": {
    "htb": {
      "command": "htb-mcp",
      "env": {
        "HTB_APP_TOKEN": "YOUR_HTB_APP_TOKEN"
      }
    }
  }
}
```

### Option B: run module directly from source

```json
{
  "mcpServers": {
    "htb": {
      "command": "python3.10",
      "args": ["-m", "htb_mcp"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/htb-mcp/src",
        "HTB_APP_TOKEN": "YOUR_HTB_APP_TOKEN"
      }
    }
  }
}
```

## Running Manually

```bash
HTB_APP_TOKEN=YOUR_HTB_APP_TOKEN htb-mcp
```

## Response Envelope

All tool responses follow one envelope:

Success:

```json
{
  "ok": true,
  "data": {}
}
```

Error:

```json
{
  "ok": false,
  "error": {
    "type": "ErrorType",
    "message": "Human readable message",
    "details": {}
  }
}
```

## Tool Catalog

User:
- `htb_user_get`
- `htb_user_activity`
- `htb_user_respect`

Machine:
- `htb_machine_list`
- `htb_machine_get`
- `htb_machine_active`
- `htb_machine_start`
- `htb_machine_stop`
- `htb_machine_reset`
- `htb_machine_extend`
- `htb_machine_submit_flag`
- `htb_machine_rate_flag`

Challenge:
- `htb_challenge_list`
- `htb_challenge_search`
- `htb_challenge_get`
- `htb_challenge_submit`
- `htb_challenge_instance_start`
- `htb_challenge_instance_stop`
- `htb_challenge_instance_status`

Prolabs and Certificates:
- `htb_prolabs_list`
- `htb_prolabs_get`
- `htb_prolabs_submit`
- `htb_certificate_list`

VPN:
- `htb_vpn_servers_list`
- `htb_vpn_accessible_list`
- `htb_vpn_switch`
- `htb_vpn_active_connections`

Pwnbox:
- `htb_pwnbox_status`
- `htb_pwnbox_terminate`

Sherlocks:
- `htb_sherlock_categories`
- `htb_sherlock_list`

Badges:
- `htb_badges_list`

Seasons:
- `htb_season_list`
- `htb_season_details`
- `htb_season_current_machines`

## Development

Run tests:

```bash
PYTHONPATH=src python3.10 -m pytest -q
```

Quick syntax check:

```bash
PYTHONPATH=src python3.10 -m py_compile src/htb_mcp/*.py src/htb_mcp/htbapi/*.py
```

## Project Layout

```text
htb-mcp/
  src/htb_mcp/
    server.py
    tools.py
    config.py
    client_factory.py
    serialization.py
    htbapi/
  tests/
```

## Notes

- This project depends on HTB API behavior and can be affected by HTB-side changes.
- Keep your `HTB_APP_TOKEN` secret.