playmetrics_mcp

First MCP server for the PlayMetrics youth-sports club management platform. Read-only access to clubs, teams, players, schedule, registrations, and payments - so Claude, Cursor, or any MCP client can answer questions about your club's day-to-day operations.

MIT licensed. Built on the mcp-vertical-template standards: shared httpx.AsyncClient with pooling + transport retries, typed exception hierarchy, respx tests, structlog logging, py.typed marker, ruff full-rule-set, mypy --strict, JSONL audit log per tool call.

Why this exists

PlayMetrics is the dominant youth-sports club management platform in the US - purpose-built for the messy workflows of running a club, league, or tournament (registrations, rosters, schedules, payments, communications). The platform just acquired SportsEngine (the AYSO / Pop Warner stack), which makes it the de-facto default for thousands of clubs.

But PlayMetrics does not publish a first-party developer API. Club directors spend hours each week pulling rosters, schedules, and registration status by hand - exactly the kind of work an AI agent should be able to do.

This server reverse-engineers the same api.playmetrics.com backend the web app uses, exposes it as MCP tools, and ships the engineering discipline B2B procurement teams expect (audit logs, isError-compliance, retry with backoff, structured errors).

Features

13 tools across 6 resource groups:

Group	Tools
Diagnostic	health_check, get_current_role
Clubs	list_clubs, get_club
Teams	list_teams, get_team
Players	list_players, get_player
Schedule / events	list_events, get_event, get_schedule, list_upcoming_practices
Registrations & payments	list_registrations, get_registration, list_payments

All tools:

• Raise on failure (FastMCP sets isError=true on the wire - agents can't get stuck retrying).
• Write one JSONL audit record per call (stderr by default, or PLAYMETRICS_AUDIT_LOG=/path/to/audit.jsonl).
• Map HTTP failures to a typed exception hierarchy (PlaymetricsAuthError, PlaymetricsNotFoundError, PlaymetricsRateLimitError, PlaymetricsAPIError, PlaymetricsConnectionError).
• Retry transient 5xx / 429 with exponential backoff + full jitter, honoring Retry-After.
• Use a shared httpx.AsyncClient with connection pooling and 3 transport retries.

Install

git clone https://github.com/sanjibani/playmetrics_mcp
cd playmetrics_mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Auth setup (3 minutes)

PlayMetrics auth is session-based against api.playmetrics.com, not API-key-based. You need three things from your web session:

1. Email + password - your PlayMetrics login.
2. role_id - a query parameter PlayMetrics uses to scope a user to one of their many possible contexts (a director might be admin of one club and parent of another player in a different club, each with its own role_id).

To find your role_id:

1. Log in to https://app.playmetrics.com in your browser.
2. Open DevTools → Network tab.
3. Reload the page or click around the Schedule tab.
4. Find any request to api.playmetrics.com (e.g. /schedule or /events).
5. Copy the role_id query parameter value from the request URL.

Then set:

export PLAYMETRICS_USERNAME='you@example.com'
export PLAYMETRICS_PASSWORD='your-password'
export PLAYMETRICS_ROLE_ID='the-role-id-from-the-url'
playmetrics_mcp

(Or supply PLAYMETRICS_SESSION_TOKEN=... if you've already minted one via the /login endpoint.)

Example agent prompts

• "List the teams I'm coaching this season." → list_teams
• "What's the schedule for team X next two weeks?" → list_events(start=today, end=today+14d, team_id=X)
• "When's our next practice?" → list_upcoming_practices(team_id=X, days=14)
• "Show me registrations still pending payment." → list_registrations(status=pending)
• "Pull today's deposits for the treasurer." → list_payments(status=paid, ...) + filter client-side

Architecture notes

Reverse-engineered API surface

PlayMetrics does not publish an API reference. The endpoints here were observed in the web app's network traffic and follow the convention: plural nouns, role_id scoped, kebab-case for compound paths (e.g. /events/upcoming).

If PlayMetrics renames an endpoint, point the corresponding method in client.py at the new path - the rest of the stack (auth, retry, audit, typed exceptions) is unaffected. PRs welcome.

Login flow

PlaymetricsClient.__init__ does a synchronous POST /login (using the sync httpx client - no event loop yet) if no PLAYMETRICS_SESSION_TOKEN is present, then reuses the resulting bearer token for every async call that follows. The password is held in memory for re-login, but never logged (the audit redactor strips any field named password or PLAYMETRICS_PASSWORD).

isError-compliance

Every tool body is wrapped so that any PlaymetricsError propagates out and FastMCP wraps it as a ToolError on the wire response - setting isError=true so the agent sees a real failure rather than an error-shaped string. The Blackwell Systems audit (54 MCPs / 20 bugs) and MCPTox benchmark both flagged the opposite pattern as the most common MCP bug class; this server does not regress.

Development

pytest                     # run all tests (no live API)
pytest -m "not integration" # default - no live API
ruff check src tests       # lint
ruff format --check src tests
mypy src                   # type check (strict)

Tests use respx to intercept httpx calls - no live API traffic. The login flow is exercised in-process via respx mocks.

Distribution

Distribution state file: ~/.mavis/state/vertical-mcp/dist/playmetrics-mcp.json. Picked up daily by the vertical-mcp-distribute cron for auto-submission to awesome-mcp-servers, mcp.so, GitHub topics, etc.

Sister MCPs in the same portfolio

• sanjibani/hawksoft-mcp - independent insurance agencies
• sanjibani/open-dental-mcp - dental practices
• sanjibani/ezyvet-mcp - veterinary clinics
• sanjibani/jobber-mcp - home service businesses
• sanjibani/practicepanther-mcp - solo/small-firm legal
• sanjibani/realm-mp-mcp - church / nonprofit (Realm ACS, MinistryPlatform)
• sanjibani/fieldroutes-mcp - pest control / lawn care
• sanjibani/cox-automotive-mcp - auto dealerships
• sanjibani/qualia-mcp - title & escrow
• sanjibani/campspot-mcp - private campgrounds
• sanjibani/cleancloud-mcp - laundromat / dry cleaners
• Custom MCP engagements: https://sanjibani.github.io/mcp-services/

License

MIT. See LICENSE. Author: Sanjibani Choudhury schoudhury1991@gmail.com.

Disclaimer

This is an independent, community-built integration. It is not affiliated with, endorsed by, or supported by PlayMetrics, Inc. Use at your own risk - the underlying API is reverse-engineered and may change without notice.