protrainup-mcp

An MCP (Model Context Protocol) server that exposes a ProTrainUp club account (https://protrainup.com) to AI agents such as Hermes.

ProTrainUp does not publish an official API, but its mobile apps talk to an undocumented API (Laravel + JWT). This server is a thin, deliberately read-only wrapper over that API.

Established API facts (reconnaissance 2026-10-01, verified live)

Every ProTrainUp club panel (subdomain, e.g. your-club.protrainup.com) serves its own copy of the same API — an account only works on its own club's subdomain, so set PROTRAINUP_BASE_URL to the address you log into (default https://api.protrainup.com).

Error format: {"message": "...", "status_code": N} (messages are Polish, e.g. "Pole login jest wymagane."). Missing token: 401 "Token not provided". Controllers live in the App\Api\V1\Controllers\* namespace.

Naming note: the API uses singular resource names (conversation, tests, exercises) and nests resources the same way — when exploring manually via ptu_api_get, try the singular form first.

Club wall (web routes, panel session — not JWT)

Some data — notably the club activity stream — is not in the mobile /api but in web panel routes protected by the panel session (cookie), not the JWT. The server logs in in parallel with the login form (CSRF + username/password) and keeps both sessions:

Stream types: team (team id), announcements (club announcements scope id), user/group (200, may be empty), club/organization (403 for a parent-level account). Web routes answer JSON with Accept: application/json, but their 404s are HTML pages.

POSTs need the post-login CSRF token (the csrf-token meta tag on panel pages, sent as the X-CSRF-TOKEN header); it is fetched lazily and refreshed on a 419 mismatch.

Players/payments-type paths do not exist in this API (~100 names checked — 404). Panel data likely flows through other (web) routes; a possible future step, e.g. browser-automation-based MCP tools.

The API is undocumented and may change without notice; handling of 401 with automatic re-login is built in.

Related MCP server: wFirma MCP

Installation

Requires Python 3.10+ and uv (or pip).

uv sync            # creates .venv and installs dependencies
uv run pytest      # tests (offline, no account needed)

Configuration

Credentials (the same ones you use for the app.protrainup.com panel) can be provided in two ways — real environment variables always take precedence:

1. A .env file in the project directory (auto-loaded, gitignored):

   cp .env.example .env   # then open .env and fill in login and password

2. Environment variables of the process (the env block in an MCP client config, export in a shell, or setx on Windows):

MCP tools

Connecting an MCP client (e.g. Hermes, Claude Desktop, Cursor)

The server speaks the stdio transport by default. Manual run:

uv run protrainup-mcp

Example MCP client configuration (Claude Desktop / most MCP clients format); adjust the path to your clone:

{
  "mcpServers": {
    "protrainup": {
      "command": "uv",
      "args": ["--directory", "C:\\\\path\\\\to\\\\protrainup-mcp", "run", "protrainup-mcp"],
      "env": {
        "PROTRAINUP_LOGIN": "your-login",
        "PROTRAINUP_PASSWORD": "your-password"
      }
    }
  }
}

If your agent does not support MCP natively, use any function-calling→MCP bridge (e.g. the mcp Python SDK as a client) — all tools return JSON as text, so they map 1:1 onto functions.

Docker deployment (HTTP transport)

For agents running in containers (e.g. Hermes on Proxmox) the server can run as an HTTP sidecar instead of a stdio subprocess:

docker compose up -d --build   # uses compose.yml and .env from the project dir

MCP endpoint: http://protrainup-mcp:8000/mcp (service name on the compose network). Transport knobs:

Security note: the HTTP endpoint has no built-in authentication — anyone who can reach the port uses your ProTrainUp account. Do not publish the port (ports:); keep it on the internal compose network or behind an authenticating reverse proxy.

If your agent (and its container) supports stdio servers, it is simpler to install the package inside the agent's container:

pip install git+https://github.com/lookassh/protrainup-mcp.git
# then in the agent's MCP config: command "protrainup-mcp" + PROTRAINUP_* env

Verification

# after setting PROTRAINUP_LOGIN/PROTRAINUP_PASSWORD
uv run python -c "from protrainup_mcp.config import load_config; from protrainup_mcp.client import ProTrainUpClient; print(ProTrainUpClient(load_config()).whoami())"

Agent skill (.agents/skills/protrainup/)

The repo ships a skill that teaches coding/agent tools how to use the ptu_* tools well: which tool answers which question, working workflows (week schedule, unread messages, club news), gotchas verified against the live API, and privacy guidance for minors' data. Agents supporting the .agents/skills convention (e.g. ZCode) discover it automatically when the repo is open; otherwise point your agent at the SKILL.md.

Caveats

• The API is private/undocumented — you use it at your own risk and only with your own club account; it is worth asking ProTrainUp support about official access.

• The server performs read-only (GET) operations only. Write operations would have to be added deliberately later.