{"id":48093477,"url":"https://github.com/aserper/spark-mcp","last_synced_at":"2026-04-04T15:33:35.412Z","repository":{"id":342951662,"uuid":"1175746181","full_name":"aserper/spark-mcp","owner":"aserper","description":"MCP server for Spark Membership platform — martial arts studio class scheduling, bookings, and management","archived":false,"fork":false,"pushed_at":"2026-04-03T01:13:28.000Z","size":1447,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T11:19:28.697Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aserper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-08T05:28:25.000Z","updated_at":"2026-04-03T01:13:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aserper/spark-mcp","commit_stats":null,"previous_names":["aserper/spark-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aserper/spark-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserper%2Fspark-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserper%2Fspark-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserper%2Fspark-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserper%2Fspark-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aserper","download_url":"https://codeload.github.com/aserper/spark-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserper%2Fspark-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31403959,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T15:33:30.126Z","updated_at":"2026-04-04T15:33:35.388Z","avatar_url":"https://github.com/aserper.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![spark-mcp logo](logo.png)\n\n# spark-mcp\n\nMCP server for the [Spark Membership](https://sparkmembership.com/) platform — a CRM used by hundreds of martial arts studios. Manage class scheduling, bookings, attendance, and more through any MCP client (e.g. Claude Code).\n\nBuilt by reverse-engineering the Spark Membership mobile app API.\n\n## Quick Start (Docker)\n\nDocker is the preferred way to run spark-mcp — no Python install needed.\n\n**1. Pull the image:**\n\n```bash\ndocker pull ghcr.io/aserper/spark-mcp:latest\n```\n\n**2. Add to your Claude Code config** (`.mcp.json` in your project root or `~/.claude/settings.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"spark\": {\n      \"type\": \"stdio\",\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"--rm\", \"-i\",\n        \"-e\", \"SPARK_EMAIL\", \"-e\", \"SPARK_PASSWORD\", \"-e\", \"SPARK_LOCATION_ID\",\n        \"ghcr.io/aserper/spark-mcp\"],\n      \"env\": {\n        \"SPARK_EMAIL\": \"your-email@example.com\",\n        \"SPARK_PASSWORD\": \"your-password\",\n        \"SPARK_LOCATION_ID\": \"1234\"\n      }\n    }\n  }\n}\n```\n\n**3. Restart Claude Code** and start asking about your classes.\n\n## Finding your Location ID\n\nEvery studio on Spark Membership has a numeric location ID. Use the included `find_location.py` script to look it up.\n\n**Search by state code:**\n\n```bash\n# Docker\ndocker run --rm --entrypoint python ghcr.io/aserper/spark-mcp find_location.py MA\n\n# Local\npython find_location.py MA\n```\n\n**Search by studio name:**\n\n```bash\n# Docker\ndocker run --rm --entrypoint python ghcr.io/aserper/spark-mcp find_location.py \"jiu jitsu\"\n\n# Local\npython find_location.py natick\n```\n\n**Interactive mode** (lists countries, states, then locations):\n\n```bash\n# Docker\ndocker run --rm -it --entrypoint python ghcr.io/aserper/spark-mcp find_location.py\n\n# Local\npython find_location.py\n```\n\nExample output:\n\n```\n    ID  Name\n    --  ----\n  1588  Metrowest Academy of Jiu Jitsu (Natick)\n  6218  Villaris Martial Arts of Natick (Natick)\n```\n\nUse the `ID` value as your `SPARK_LOCATION_ID`.\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `login` | Authenticate with email, password, and location ID |\n| `list_classes` | List available classes for a given date |\n| `my_classes` | List classes you're currently enrolled in |\n| `book_class` | Book a class by roster ID and date |\n| `cancel_booking` | Cancel a class reservation |\n| `join_waitlist` | Join the waitlist for a full class |\n| `get_waitlist` | List classes you're on the waitlist for |\n| `checkin` | Check in to a class |\n| `dashboard` | Get the studio dashboard overview |\n| `attendance` | View attendance history |\n| `announcements` | Get studio announcements |\n| `memberships` | Get membership status |\n\n## Usage Examples\n\nOnce configured, you can ask Claude things like:\n\n- \"What classes are available this Saturday?\"\n- \"Book me into the 9am Ninjas class on March 21\"\n- \"What am I signed up for?\"\n- \"Cancel my Saturday booking\"\n- \"Show my attendance history\"\n- \"Any new announcements from the studio?\"\n\n## Alternative: Local Install\n\nIf you prefer not to use Docker:\n\n```bash\ngit clone https://github.com/aserper/spark-mcp.git\ncd spark-mcp\nuv venv \u0026\u0026 source .venv/bin/activate\nuv pip install -e .\n```\n\nThen configure Claude Code with:\n\n```json\n{\n  \"mcpServers\": {\n    \"spark\": {\n      \"type\": \"stdio\",\n      \"command\": \"/path/to/spark-mcp/.venv/bin/python\",\n      \"args\": [\"-m\", \"spark_mcp\"],\n      \"env\": {\n        \"SPARK_EMAIL\": \"your-email@example.com\",\n        \"SPARK_PASSWORD\": \"your-password\",\n        \"SPARK_LOCATION_ID\": \"1234\"\n      }\n    }\n  }\n}\n```\n\n## Authentication\n\nCredentials can be provided in three ways:\n\n1. **Environment variables** (recommended) — set `SPARK_EMAIL`, `SPARK_PASSWORD`, and `SPARK_LOCATION_ID` in your MCP config. The server auto-authenticates on first tool call.\n2. **`login` tool** — call it manually at runtime without any env vars.\n3. **Mix** — set email/password in env vars and use `login` to switch locations.\n\nTokens are automatically refreshed when they expire.\n\n## API Reference\n\nAll endpoints hit `https://mobileapi.sparkmembership.com/api/student/`. Auth uses Bearer tokens with automatic refresh. See [`api-discovery.md`](api-discovery.md) for the full endpoint reference.\n\n## OpenClaw / Claude Code Skill (Optional)\n\nFor a higher-level, natural language interface, install the `spark` skill:\n\n```bash\n# Via mcporter\nmcporter config import spark ./openclaw-skill/SKILL.md\n\n# Or manually copy to your OpenClaw skills directory\ncp -r openclaw-skill ~/.openclaw/skills/spark\n```\n\nThen use natural language commands:\n\n```bash\nspark who                          # Discover family members\nspark book hailey thursday         # Book Hailey for next Thursday\nspark bulk \"ily saturdays 4 weeks\" # Bulk book Saturdays\nspark my-classes                   # Show current bookings\n```\n\nSee [openclaw-skill/SKILL.md](openclaw-skill/SKILL.md) for full documentation.\n\n## Requirements\n\n- Docker (preferred), or Python 3.11+\n- A Spark Membership account (through your studio's app)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faserper%2Fspark-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faserper%2Fspark-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faserper%2Fspark-mcp/lists"}