https://github.com/aserper/spark-mcp
MCP server for Spark Membership platform — martial arts studio class scheduling, bookings, and management
https://github.com/aserper/spark-mcp
Last synced: 3 months ago
JSON representation
MCP server for Spark Membership platform — martial arts studio class scheduling, bookings, and management
- Host: GitHub
- URL: https://github.com/aserper/spark-mcp
- Owner: aserper
- Created: 2026-03-08T05:28:25.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-03T01:13:28.000Z (3 months ago)
- Last Synced: 2026-04-03T11:19:28.697Z (3 months ago)
- Language: Python
- Size: 1.38 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# spark-mcp
MCP 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).
Built by reverse-engineering the Spark Membership mobile app API.
## Quick Start (Docker)
Docker is the preferred way to run spark-mcp — no Python install needed.
**1. Pull the image:**
```bash
docker pull ghcr.io/aserper/spark-mcp:latest
```
**2. Add to your Claude Code config** (`.mcp.json` in your project root or `~/.claude/settings.json`):
```json
{
"mcpServers": {
"spark": {
"type": "stdio",
"command": "docker",
"args": ["run", "--rm", "-i",
"-e", "SPARK_EMAIL", "-e", "SPARK_PASSWORD", "-e", "SPARK_LOCATION_ID",
"ghcr.io/aserper/spark-mcp"],
"env": {
"SPARK_EMAIL": "your-email@example.com",
"SPARK_PASSWORD": "your-password",
"SPARK_LOCATION_ID": "1234"
}
}
}
}
```
**3. Restart Claude Code** and start asking about your classes.
## Finding your Location ID
Every studio on Spark Membership has a numeric location ID. Use the included `find_location.py` script to look it up.
**Search by state code:**
```bash
# Docker
docker run --rm --entrypoint python ghcr.io/aserper/spark-mcp find_location.py MA
# Local
python find_location.py MA
```
**Search by studio name:**
```bash
# Docker
docker run --rm --entrypoint python ghcr.io/aserper/spark-mcp find_location.py "jiu jitsu"
# Local
python find_location.py natick
```
**Interactive mode** (lists countries, states, then locations):
```bash
# Docker
docker run --rm -it --entrypoint python ghcr.io/aserper/spark-mcp find_location.py
# Local
python find_location.py
```
Example output:
```
ID Name
-- ----
1588 Metrowest Academy of Jiu Jitsu (Natick)
6218 Villaris Martial Arts of Natick (Natick)
```
Use the `ID` value as your `SPARK_LOCATION_ID`.
## Tools
| Tool | Description |
|------|-------------|
| `login` | Authenticate with email, password, and location ID |
| `list_classes` | List available classes for a given date |
| `my_classes` | List classes you're currently enrolled in |
| `book_class` | Book a class by roster ID and date |
| `cancel_booking` | Cancel a class reservation |
| `join_waitlist` | Join the waitlist for a full class |
| `get_waitlist` | List classes you're on the waitlist for |
| `checkin` | Check in to a class |
| `dashboard` | Get the studio dashboard overview |
| `attendance` | View attendance history |
| `announcements` | Get studio announcements |
| `memberships` | Get membership status |
## Usage Examples
Once configured, you can ask Claude things like:
- "What classes are available this Saturday?"
- "Book me into the 9am Ninjas class on March 21"
- "What am I signed up for?"
- "Cancel my Saturday booking"
- "Show my attendance history"
- "Any new announcements from the studio?"
## Alternative: Local Install
If you prefer not to use Docker:
```bash
git clone https://github.com/aserper/spark-mcp.git
cd spark-mcp
uv venv && source .venv/bin/activate
uv pip install -e .
```
Then configure Claude Code with:
```json
{
"mcpServers": {
"spark": {
"type": "stdio",
"command": "/path/to/spark-mcp/.venv/bin/python",
"args": ["-m", "spark_mcp"],
"env": {
"SPARK_EMAIL": "your-email@example.com",
"SPARK_PASSWORD": "your-password",
"SPARK_LOCATION_ID": "1234"
}
}
}
}
```
## Authentication
Credentials can be provided in three ways:
1. **Environment variables** (recommended) — set `SPARK_EMAIL`, `SPARK_PASSWORD`, and `SPARK_LOCATION_ID` in your MCP config. The server auto-authenticates on first tool call.
2. **`login` tool** — call it manually at runtime without any env vars.
3. **Mix** — set email/password in env vars and use `login` to switch locations.
Tokens are automatically refreshed when they expire.
## API Reference
All 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.
## OpenClaw / Claude Code Skill (Optional)
For a higher-level, natural language interface, install the `spark` skill:
```bash
# Via mcporter
mcporter config import spark ./openclaw-skill/SKILL.md
# Or manually copy to your OpenClaw skills directory
cp -r openclaw-skill ~/.openclaw/skills/spark
```
Then use natural language commands:
```bash
spark who # Discover family members
spark book hailey thursday # Book Hailey for next Thursday
spark bulk "ily saturdays 4 weeks" # Bulk book Saturdays
spark my-classes # Show current bookings
```
See [openclaw-skill/SKILL.md](openclaw-skill/SKILL.md) for full documentation.
## Requirements
- Docker (preferred), or Python 3.11+
- A Spark Membership account (through your studio's app)