🏋️‍♀️ Huppa CLI

A CLI tool and MCP server for Huppa — browse gym classes, book them, and manage bookings from the command line or through AI assistants like Claude.

Disclaimer: This is an unofficial, community-built project and is not affiliated with, endorsed by, or approved by Huppa. It interacts with Huppa's public API using your personal credentials. Use at your own risk — the author is not responsible for any account restrictions, data loss, or other consequences. Huppa may change their API at any time, which could break this tool without notice.

⚙️ Installation

Prerequisites: Python 3.11+, uv

git clone https://github.com/maxzw/huppa-cli.git
cd huppa-cli
uv sync

# Run one-time interactive setup (stores credentials in OS keychain)
uv run huppa auth setup

🔑 Authentication

The setup command prompts for email/password/subdomain and stores them securely in your system keychain.

To find your subdomain, open your Huppa gym page URL and use the first part before .huppa.app.

Example: https://mygym.huppa.app/me → subdomain is mygym

uv run huppa auth setup   # interactive credential setup
uv run huppa auth whoami  # show current authenticated user
uv run huppa auth logout  # clear stored credentials

Profile-specific authentication:

HUPPA_PROFILE=work-gym uv run huppa auth setup
HUPPA_PROFILE=work-gym uv run huppa auth whoami

Environment-variable authentication:

HUPPA_EMAIL="you@example.com" \
HUPPA_PASSWORD="your-password" \
HUPPA_SUBDOMAIN="mygym" \
uv run huppa classes 2026-03-08

🛠️ CLI Usage

All commands output structured JSON.

# List classes for a date
uv run huppa classes 2026-03-08

# List classes for multiple dates
uv run huppa classes 2026-03-08 2026-03-09

# Show upcoming bookings
uv run huppa bookings
uv run huppa bookings --filter past --per-page 10

# Show memberships
uv run huppa memberships

# Book a class (use organization_id and occurrence_id from `huppa classes`)
uv run huppa book <organization_id> <occurrence_id>

# Cancel a booking
uv run huppa cancel <organization_id> <occurrence_id>

# Waitlist management
uv run huppa waitlist join <organization_id> <occurrence_id>
uv run huppa waitlist leave <organization_id> <occurrence_id>

# Show all available commands
uv run huppa --help

🤖 MCP Server

The CLI includes a built-in MCP server for AI assistants:

uv run huppa mcp

Connecting to Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "huppa": {
      "command": "/full/path/to/uv",
      "args": ["--directory", "/absolute/path/to/huppa-cli", "run", "huppa", "mcp"]
    }
  }
}

Find uv path with which uv. Use full paths (not "uv") because Claude Desktop starts MCP servers with limited PATH.

MCP Tools

Tool	Description
get_classes(date)	List available gym classes for a given date (YYYY-MM-DD).
get_classes_multiple_dates(list_of_dates)	Get classes for multiple dates at once.
book_class(organization_id, occurrence_id)	Book a class.
cancel_booking(organization_id, occurrence_id)	Cancel an existing booking.
join_waitlist(organization_id, occurrence_id)	Join the waitlist for a full class.
leave_waitlist(organization_id, occurrence_id)	Leave the waitlist.
get_my_bookings(filter, per_page, page)	List bookings and waitlists.
get_memberships()	Get memberships with credit balance and payment dates.

📋 License

MIT