HackyEaster Solver

MCP server for Claude-driven HackyEaster CTF solving. Uses Scrapling for page fetching and exposes CTF utility tools so Claude can reason through challenges, submit answers via Playwright, and iterate.

Setup

Quick install (no clone needed)

Add to your ~/.mcp.json:

{
  "mcpServers": {
    "hackyeaster": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/cloudwarriors-ai/hackyeaster-solver", "hackyeaster-mcp"]
    }
  }
}

Restart Claude Code. The he_* tools will appear in the MCP servers panel.

Local development

If you want to modify the server or keep persistent state in a known location:

git clone https://github.com/cloudwarriors-ai/hackyeaster-solver.git
cd hackyeaster-solver
uv sync

Then in ~/.mcp.json, point at your local clone:

{
  "mcpServers": {
    "hackyeaster": {
      "command": "bash",
      "args": ["-c", "uv run --directory /path/to/hackyeaster-solver python -m hackyeaster_mcp.server"]
    }
  }
}

Tools

Scraping

Tool	Description
he_discover_challenges	Scrape hackyeaster.com and return available challenges
he_fetch_challenge	Fetch and parse a specific challenge page
he_fetch_raw	Fetch any URL and return raw HTML

CTF Utilities

Tool	Description
he_decode	Decode: base64, hex, url, binary, morse, decimal, octal, base32
he_transform	Transform: caesar, rot13, swap_pairs, reverse, rail_fence, vigenere, xor, atbash
he_analyze_image	Download image for visual analysis + QR/barcode detection
he_hash	Compute hashes: md5, sha1, sha256, sha512

State

Tool	Description
he_log_attempt	Record a solve attempt
he_get_progress	View all attempts and solved challenges
he_validate_flag	Check if text matches flag format he20XX{...}

How It Works

Claude is the solver. The MCP server provides the tools; Claude provides the reasoning.

1. he_discover_challenges — scrape the site for challenges
2. he_fetch_challenge — read challenge content, hints, embedded data
3. Claude reasons about the puzzle, calls he_decode / he_transform / he_analyze_image as needed
4. Playwright MCP (separate, already available in Claude Code) handles form interaction and answer submission
5. he_log_attempt tracks what was tried and what worked

Requirements

• Python 3.11+
• uv
• Claude Code with MCP support
• Playwright MCP server (for answer submission when challenges go live)

Architecture

Claude (solver brain)
  |
  +-- hackyeaster MCP -- Scrapling fetch + CTF utils + state
  |
  +-- playwright MCP --- form interaction, submit answers, screenshots