@spotfitr/mcp

MCP server that exposes the Spotfitr API as tools for Claude. Allows trainers and clients to manage sessions, bookings, and clients directly from Claude Desktop or any MCP-compatible AI client.

Architecture decisions

Transport: stdio (local)

The server runs as a local subprocess of the AI client (Claude Desktop). Each user runs their own isolated process — there is no shared state between users, no open network port, and credentials never leave the user's machine except when calling the Spotfitr API.

This was chosen over an HTTP remote server because:

• No infrastructure required (no always-on server, no TLS setup)
• Security model is trivial: one process = one user, fully isolated auth state
• The target users (fitness professionals) use Claude Desktop, so npm install is feasible
• A remote HTTP server would require rewriting the auth state model to be per-session, adding OAuth, rate limiting, and ongoing hosting costs — complexity that adds no real value for this use case

Authentication: environment variables only

Credentials are passed exclusively via SPOTFITR_EMAIL and SPOTFITR_PASSWORD environment variables, set in the Claude Desktop config file. A login tool that accepted credentials as parameters was considered and rejected: tool parameters appear in Claude's conversation context and tool call logs, which would expose the password to the model and any logging infrastructure.

Authorization: delegated to the API

The MCP server does not enforce any role-based access control itself. It passes the JWT from the Spotfitr API to every request and lets the API enforce permissions (OWNER vs CLIENT). Tool descriptions document which role each tool requires, but enforcement happens server-side.

Error handling: sanitized

API errors are filtered before being returned to the LLM. Only the API's own error field is forwarded (e.g. "Session is full"), never raw stack traces or internal error details. This prevents leaking implementation details through the model context.

URL security: HTTPS enforced at startup

If SPOTFITR_API_URL is set to a non-HTTPS URL (and is not localhost), the server refuses to start. This prevents the JWT from being transmitted in plaintext by misconfiguration.

Installation

Requires Node.js 18 or later.

The package is published to npm as @spotfitr/mcp. Users do not need to install it manually — npx handles it automatically.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "spotfitr": {
      "command": "npx",
      "args": ["-y", "@spotfitr/mcp"],
      "env": {
        "SPOTFITR_EMAIL": "[email protected]",
        "SPOTFITR_PASSWORD": "your-password",
        "SPOTFITR_API_URL": "https://api.spotfitr.com"
      }
    }
  }
}

Restart Claude Desktop after saving. Claude will have access to all Spotfitr tools automatically.

Claude Code (CLI)

claude mcp add spotfitr \
  -e [email protected] \
  -e SPOTFITR_PASSWORD=your-password \
  -e SPOTFITR_API_URL=https://api.spotfitr.com \
  -- npx -y @spotfitr/mcp

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | SPOTFITR_EMAIL | Yes | — | Spotfitr account email | | SPOTFITR_PASSWORD | Yes | — | Spotfitr account password | | SPOTFITR_API_URL | No | http://localhost:3001/api | Spotfitr API base URL. Must be HTTPS for non-localhost URLs. |

If SPOTFITR_EMAIL or SPOTFITR_PASSWORD are missing, the server starts but all tool calls will fail until credentials are provided. Auto-login errors are non-fatal and logged to stderr.

Available tools

Auth

| Tool | Role | Description | |------|------|-------------| | get_current_user | Any | Get the profile of the authenticated user | | get_auth_status | Any | Check if the server is authenticated and see basic user info |

Sessions

| Tool | Role | Description | |------|------|-------------| | list_sessions | Any | List sessions within an optional date range | | create_session | OWNER | Create a new individual training session | | update_session | OWNER | Update date, times, capacity, or cancel a session | | delete_session | OWNER | Permanently delete a session | | get_session_bookings | OWNER | List all confirmed bookings for a session (with client details) | | get_session_attendees | CLIENT | List names and profile pictures of confirmed attendees |

Session types

| Tool | Role | Description | |------|------|-------------| | list_session_types | Any | List all workout types (e.g. CrossFit, Yoga, HIIT) | | create_session_type | OWNER | Create a new workout type with name, description, and color | | update_session_type | OWNER | Update name, description, or color of a workout type | | delete_session_type | OWNER | Delete a workout type (fails if sessions are using it) |

Recurrence rules

| Tool | Role | Description | |------|------|-------------| | list_recurrence_rules | OWNER | List all recurring session rules | | create_recurrence_rule | OWNER | Create a recurring rule that auto-generates sessions | | delete_recurrence_rule | OWNER | Delete a rule and its future unbooked sessions |

Clients

| Tool | Role | Description | |------|------|-------------| | list_clients | OWNER | List all active clients with their monthly booking count | | list_archived_clients | OWNER | List archived (inactive) clients | | create_client | OWNER | Add a new client and send them an invitation email | | update_client | OWNER | Update name, email, or monthly session limit | | delete_client | OWNER | Delete a client (fails if they have any bookings) | | archive_client | OWNER | Deactivate a client without deleting them | | unarchive_client | OWNER | Reactivate an archived client |

Bookings

| Tool | Role | Description | |------|------|-------------| | list_my_bookings | CLIENT | List upcoming confirmed bookings | | get_my_usage | CLIENT | Get booking usage for the current month vs the session limit | | book_session | CLIENT | Book a spot in a session | | cancel_booking | CLIENT | Cancel a booking (subject to cancellation window) |

Waitlist

| Tool | Role | Description | |------|------|-------------| | list_my_waitlist | CLIENT | List sessions you are on the waitlist for | | join_waitlist | CLIENT | Join the waitlist for a full session | | leave_waitlist | CLIENT | Remove yourself from the waitlist |

Subscription

| Tool | Role | Description | |------|------|-------------| | get_subscription_info | OWNER | Get plan (FREE/PRO), status, and client usage vs limit |

Local development

cd mcp
npm install
cp .env.example .env   # fill in your credentials
npm run dev

The dev script uses tsx --watch for hot reload.

To test with Claude Code locally before publishing:

npm run build
claude mcp add spotfitr-local \
  -e [email protected] \
  -e SPOTFITR_PASSWORD=your-password \
  -e SPOTFITR_API_URL=http://localhost:3001/api \
  -- node /absolute/path/to/spotfitr/mcp/dist/index.js

Publishing

The package is published to npm under the @spotfitr org scope.

cd mcp
npm version patch   # or minor / major
npm publish         # runs build automatically via prepublishOnly

Requires npm login with an account that has publish access to the @spotfitr org.