<p align="center">
  <img src="assets/logo.png" alt="TryHackMe Logo" width="240" />
</p>

<h1 align="center">TryHackMe MCP Server</h1>

<p align="center">
  Model Context Protocol server for searching TryHackMe rooms, extracting learning materials, and training models on hands-on cybersecurity and Linux tasks.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=flat&logo=python&logoColor=white" alt="Python" />
  <img src="https://img.shields.io/badge/Protocol-MCP-8A2BE2?style=flat" alt="MCP" />
  <img src="https://img.shields.io/badge/License-MIT-green.svg?style=flat" alt="License" />
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> •
  <a href="#client-configuration">Client Config</a> •
  <a href="#available-tools">Available Tools</a> •
  <a href="#authentication">Authentication</a> •
  <a href="#license">License</a>
</p>

---

## Overview

This MCP server connects your AI assistant (Claude Desktop, Antigravity IDE, Cursor, Windsurf, etc.) directly to [TryHackMe](https://tryhackme.com). It enables you to pull room descriptions, step-by-step walkthroughs, terminal commands, and questions directly into your workspace for training and reference.

### Key capabilities

- **Vercel checkpoint bypass**: Automatically handles the TryHackMe bot challenge in the background, caching clearance tokens for fast subsequent API calls.
- **Account-aware extraction**: Supports session cookie (`connect.sid`) authentication to access subscriber and VIP rooms.
- **Clean Markdown export**: Converts raw HTML room materials into readable Markdown with syntax-highlighted code blocks, command snippets, and hints.
- **Curated tracks**: Includes built-in references to core learning modules across Linux, Docker, Bash scripting, networking, and security.

---

## Quick Start (Zero Clone Needed)

If you have [uv](https://docs.astral.sh/uv/) installed, you can add this MCP server directly without cloning the repository.

### 1. Claude Desktop

Open your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add the `tryhackme` entry to `mcpServers`:

```json
{
  "mcpServers": {
    "tryhackme": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/bledny1099/tryhackme-mcp",
        "tryhackme-mcp"
      ]
    }
  }
}
```

Restart Claude Desktop (`Cmd + Q` on macOS and relaunch).

---

### 2. Cursor IDE

1. Open **Cursor Settings** (`Cmd + ,` or click gear icon).
2. Go to **Features** -> **MCP Servers**.
3. Click **Add New MCP Server**.
4. Fill in:
   - **Name**: `tryhackme`
   - **Type**: `command`
   - **Command**:
     ```bash
     uvx --from git+https://github.com/bledny1099/tryhackme-mcp tryhackme-mcp
     ```

---

### 3. Remote SSE Mode (Web Clients & Connectors)

You can run the server as a standalone HTTP/SSE service that provides an endpoint URL:

```bash
uvx --from git+https://github.com/bledny1099/tryhackme-mcp tryhackme-mcp --transport sse --port 8000
```

SSE endpoint URL: `http://localhost:8000/sse`

---

## Available Tools

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `thm_check_auth` | None | Checks current authentication status and session validity. |
| `thm_search_rooms` | `query` (string), `limit` (int, default: 10) | Searches rooms by topic or keyword (e.g., `linux`, `docker`, `networking`, `bash`). |
| `thm_get_room_overview` | `room_code` (string) | Returns room metadata, difficulty, estimated time, and task outline. |
| `thm_get_task` | `room_code` (string), `task_no` (int) | Fetches full instructions, commands, and questions for a specific task. |
| `thm_get_room_full` | `room_code` (string) | Exports complete room content as a structured Markdown document. |
| `thm_get_curated_topics` | None | Lists recommended foundational learning rooms grouped by category. |

---

## Authentication

Free and public rooms work out of the box without logging in. For VIP/subscriber rooms or account-specific progress, provide your `connect.sid` session cookie.

### Option A: Interactive Login Helper (Local Clone)

```bash
git clone https://github.com/bledny1099/tryhackme-mcp.git
cd tryhackme-mcp
uv run python login.py
```
This opens a Chrome window, waits for your login on TryHackMe, and saves your session into `.env`.

### Option B: Environment Variable in MCP Config

Add `THM_SESSION` to the `env` block in your MCP client configuration:

```json
{
  "mcpServers": {
    "tryhackme": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/bledny1099/tryhackme-mcp",
        "tryhackme-mcp"
      ],
      "env": {
        "THM_SESSION": "your_connect_sid_cookie_here"
      }
    }
  }
}
```

---

## Usage Example

Once configured, your AI assistant can interact with TryHackMe:

```text
User: "Find TryHackMe rooms about Linux fundamentals and pull the content of task 2 from linuxfundamentalspart1."
```

The model calls:
1. `thm_search_rooms(query="linux")`
2. `thm_get_task(room_code="linuxfundamentalspart1", task_no=2)`

The model receives the exact theoretical notes, command syntax, and exercise questions in clean Markdown.

---

## License

[MIT](LICENSE)