hudl-mcp-server

hudl-mcp-server

An MCP (Model Context Protocol) server that connects Claude Desktop to Hudl, giving Claude live access to team stats, player stats, and game results through natural language.

---

What It Does

Ask Claude questions like:

• "Who is the leading scorer this season?"
• "What's our record against ranked opponents?"
• "Show me player stats for our last game against Beaverton."
• "How did our faceoff percentage compare between 2023 and 2024?"

Claude calls the MCP tools, retrieves live data from Hudl, and returns structured analysis — no copy-pasting, no manual exports.

---

How It Works

The server uses Playwright to authenticate with Hudl and retrieve data via a combination of page scraping and CSV export interception. A session cookie is cached after the first login so subsequent calls are fast. If Hudl requires 2FA, the browser launches in visible mode so you can complete it manually.

Claude Desktop  →  MCP Tools  →  Hudl (via Playwright)
                ←  JSON data  ←

---

Available Tools

| Tool | Description | |------|-------------| | list_seasons | Lists all available seasons with IDs, sorted newest first | | get_game_results | Season game results — scores, opponents, home/away, W/L | | get_player_stats | Full player stat export — goals, assists, shots, faceoffs, turnovers, saves, and more | | get_team_stats | Aggregated team stats — record, goals scored/allowed, win % | | get_game_stats | Per-game player stats for a single specific game | | get_box_score | Team-level box score comparison (AHS vs opponent) for a single game or full season | | clear_cache | Invalidate cached data — all, by season label, or by game |

All tools accept an optional season parameter to query historical seasons. All tools accept an optional refresh: true parameter to bypass cache and re-fetch from Hudl.

---

Project Structure

src/
  auth/
    hudlAuth.ts           — Hudl login flow, session restore, 2FA handling
  browser/
    browserManager.ts     — Playwright browser lifecycle
    networkInterceptor.ts — API endpoint discovery utilities
  cache/
    sessionCache.ts       — Read/write cached session cookies
  fetchers/
    reportsCsvFetcher.ts  — Navigate to reports page, intercept CSV export
  scrapers/
    gameResultsScraper.ts — Game results from team timeline
    gameStatsScraper.ts   — Per-game player stats with fuzzy opponent matching
    playerStatsScraper.ts — Full player stats via CSV interception
    teamStatsScraper.ts   — Team stats via CSV interception
  config.ts               — Environment variable loading
  types.ts                — TypeScript interfaces
  server.ts               — MCP server definition and tool handlers
  index.ts                — Entry point
  cli.ts                  — Interactive developer test harness

---

Setup

1. Install dependencies

npm install

This also runs playwright install chromium automatically.

2. Configure environment variables

Copy .env.example to .env and fill in your credentials:

HUDL_EMAIL=your@email.com
HUDL_PASSWORD=yourpassword
HUDL_TEAM_ID=your_team_id
HUDL_CACHE_DIR=C:/Users/<you>/hudl-mcp-server/.cache

To find your HUDL_TEAM_ID, navigate to your team page in Hudl — it's in the URL.

HUDL_CACHE_DIR should be an absolute path. Setting it explicitly ensures the cache is always written to the same location regardless of what directory the process is launched from.

3. Build

npm run build

4. Configure Claude Desktop

Add the server to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "hudl": {
      "command": "node",
      "args": ["C:/path/to/hudl-mcp-server/dist/index.js"]
    }
  }
}

Restart Claude Desktop. The Hudl tools will be available in your next conversation.

---

Testing Without Claude Desktop

A CLI lets you exercise each tool directly from the terminal:

npm run cli

Interactive menu options:

| Key | Action | |-----|--------| | 1–6 | Call each MCP tool directly and inspect the raw JSON response | | c | List all cache entries (key, age, TTL) | | ci | Inspect a cache entry — select by number, view full JSON payload | | cc | Clear cache — all entries, by season label, or by keyword | | w | Warm season — bulk-fetch and permanently cache all game stats and box scores for a season | | t | Smoke test — run all tools and report pass/fail |

Warming the cache for prior seasons

After a fresh install (or account switch), run the warm command to pre-populate the cache for completed prior seasons. This avoids re-fetching 30+ games every time you run a report:

npm run cli → w → enter "2024-2025" → y (prior/completed)
npm run cli → w → enter "2023-2024" → y (prior/completed)

Takes ~10 minutes per season on first run. Subsequent runs skip already-cached entries.

---

Notes

• First call per session may take 10–20 seconds while the browser starts and authenticates
• Session is cached in .hudl-session.json — subsequent calls reuse the session without re-logging in
• 2FA: if Hudl prompts for verification, the browser will open visibly so you can complete it manually
• Read-only: the server never modifies any data in Hudl
• .env and .hudl-session.json are excluded from version control — never commit credentials

---

Related

• alc-lacrosse-reports — companion repo that uses this MCP server to generate branded PDF game and season reports