kicksite-mcp

kicksite-mcp

First MCP (Model Context Protocol) server for theKicksite martial-arts-school management API. Read andwrite students, prospects, memberships, recurring billings, invoices, classsessions, attendance, belt promotions, communications, and notes — all inplain English from Claude, Cursor, or any MCP client.

What is Kicksite?

Kicksite is the leading SaaS for US martial-arts schools (taekwondo, karate,jiu-jitsu, MMA, Krav Maga, etc.). Schools use it to manage students, run thetrial-to-active funnel, schedule classes, take attendance, promote beltranks, and bill via EFT or credit-card autopay. Public REST API since themid-2010s — but no one had wrapped it for MCP clients until now.

Quick start

1. Create OAuth credentials in Kicksite

1. Log in to your school's Kicksite web UI (https://{yourschool}.kicksite.net)
2. Click Quick Links → Settings → Integrations
3. Click the Zapier card → Get Started
4. Kicksite will show three values — copy all of them:
   • Subdomain (the bit before .kicksite.net in your school URL)
   • Client ID
   • Client Secret (shown only once)

2. Install + run

pip install kicksite-mcp
export KICKSITE_SUBDOMAIN=dragonkarate
export KICKSITE_CLIENT_ID=<your_client_id>
export KICKSITE_CLIENT_SECRET=<your_client_secret>
kicksite_mcp

The MCP server runs over stdio. Wire it into Claude Desktop, Cursor, or anyMCP client:

{
  "mcpServers": {
    "kicksite": {
      "command": "kicksite_mcp",
      "env": {
        "KICKSITE_SUBDOMAIN": "dragonkarate",
        "KICKSITE_CLIENT_ID": "your_client_id",
        "KICKSITE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Tools (25)

Real-world queries it unlocks

• "Show me all active trial prospects from the Westside location this month"
• "Find student by phone 555-1234"
• "Who got promoted to black belt in the last 5 years?"
• "List every class session for the Adult Karate program next Tuesday"
• "Record student 1234 as late to class session 4455 with note 'traffic'"
• "Add a follow-up note to prospect 4321 - 'Call tomorrow at 5pm'"
• "List the recurring billings for student 5678 and the autopay date"
• "Find all one-time invoices from last month"
• "Send student 1234 a 'Welcome to the dojo' email"

Architecture

Built on the industry-leading patterns documented inengineering-playbook.md:

• Shared httpx.AsyncClient with connection pooling (100 max, 20 keepalive)and transport-level retries (3x) for transient network blips.
• OAuth 2 client_credentials with proactive token refresh — 60s bufferbefore expiry, asyncio.Lock to serialize concurrent refreshes, andforced refresh on a 401 (single retry, then surface the auth error).
• Typed exception hierarchy — KicksiteAuthError, KicksiteNotFoundError,KicksiteRateLimitError, KicksiteAPIError, KicksiteConnectionError —each carrying structured fields (http_status, error_code, request_id,retry_after) so callers can branch on cause, not message text.
• Application-level retry with exponential backoff + full jitter, honoringthe Retry-After header on 429s. 5xx responses are retried up to 3x.
• HTTP status dispatch table — one row per status code → exception class.Adding a new status code = one row, no new if/elif branches.
• Async iterator pagination — iter_students, iter_prospects auto-pageuntil the server returns a short page.
• isError-compliance per the Blackwell MCP security audit — every toolraises typed exceptions on failure; FastMCP wraps them withisError=true on the wire response. The old return _format_error(e)pattern (which leaves isError=false) is NOT used.
• JSONL audit logging per tool call (audit.py) — one structured recordper call with ts, tool, args (secrets redacted), result_size,is_error, error_type, duration_ms, request_id. Sink defaults tostderr; override with KICKSITE_AUDIT_LOG=/path/to/audit.jsonl. Fail-opensemantics — sink failure never breaks the tool.

Development

git clone https://github.com/sanjibani/kicksite-mcp
cd kicksite-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Code quality

• ruff — full rule set (E, F, W, I, N, UP, B, A, C4,DTZ, T20, PT, Q, RET, SIM, TID, ARG, PTH, ERA, PL,RUF)
• mypy — strict mode, every function annotated, all union types narrowed
• pytest — 50 tests via respx + hypothesis, async-mode auto, no liveAPI calls
• pre-commit — ruff + ruff-format + mypy

ruff check src tests
ruff format --check src tests
mypy src tests
pytest --cov=kicksite_mcp --cov-fail-under=80 tests

Distribution

• 89.8K-star awesome-mcp-servers PR (pending)
• mcp.so + Glama auto-index via GitHub topics
• Direct vendor outreach to Kicksite's partner team (cold-email track viavertical-mcp-distribute cron)

License

MIT — see LICENSE.

Related MCPs

Part of the same vertical-MCP portfolio (all MIT, all sanjibani/<name>-mcp):

hawksoft, open-dental, ezyvet, jobber, practicepanther,cox-automotive, qualia, campspot, cleancloud, playmetrics, foreup,storedge, courtreserve, procare, passare, funraise.

Also: mcp-shield (Tier 3 — MCP security sidecar for any untrusted MCP) andpaid-skills / skill-sandbox / mcp-skills-pack (Skills monetization andsandbox runtime).