# mindbody-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)

MCP server for [Mindbody](https://mindbodyonline.com), the vertical CRM for wellness, fitness, and beauty studios (yoga, gyms, salons, spas, training studios). 5 tools for AI agents to fetch client info, query class schedules, book clients into classes (env-gated), book appointments (env-gated), and complete shopping cart checkout (payment-gated).

As of May 2026, Mindbody does not ship an official MCP server. Multiple community attempts exist but are unofficial and self-hosted. This is the production-quality, install-ready Python rail. Shipped same-day as Mindbody's May 28 2026 Bilt Rewards distribution partnership.

## The 5 tools

| Tool | Purpose | Gated? |
|---|---|---|
| `get_client_info` | Fetch detailed client profile by ID | No, safe |
| `list_classes` | Query class schedules within a date range | No, safe |
| `book_client_to_class` | Enroll a client into a class | YES, `MINDBODY_ALLOW_BOOKINGS=true` required |
| `book_appointment` | Schedule a wellness or training appointment | YES, `MINDBODY_ALLOW_BOOKINGS=true` required |
| `checkout_shopping_cart` | Process payment for passes, services, or products | YES, `MINDBODY_ALLOW_CHECKOUT=true` required (separate flag, payment action) |

## Install

```bash
pip install mindbody-mcp
```

## Configure

```bash
export MINDBODY_API_KEY="your-mindbody-developer-api-key"
export MINDBODY_SITE_ID="your-mindbody-site-id-integer"   # use -99 for sandbox
export MINDBODY_USER_TOKEN="your-mindbody-staff-user-token"   # optional but required for client + write actions
export MINDBODY_ALLOW_BOOKINGS="false"   # set to "true" to enable booking writes
export MINDBODY_ALLOW_CHECKOUT="false"   # set to "true" to enable payment processing (separate flag for safety)
```

Get an API key in your Mindbody Developer account. The user token is obtained via staff login flow; check the Mindbody Public API V6 docs for details.

## Use with Claude Desktop

```json
{
  "mcpServers": {
    "mindbody": {
      "command": "mindbody-mcp",
      "env": {
        "MINDBODY_API_KEY": "your-mindbody-developer-api-key",
        "MINDBODY_SITE_ID": "your-mindbody-site-id-integer",
        "MINDBODY_USER_TOKEN": "your-mindbody-staff-user-token",
        "MINDBODY_ALLOW_BOOKINGS": "false",
        "MINDBODY_ALLOW_CHECKOUT": "false"
      }
    }
  }
}
```

Restart Claude Desktop. The 5 Mindbody tools are now available.

## Use case: AI front-desk + AI personal scheduler

Read-only flow (safe, default):

1. Call `get_client_info(client_id)` to load the caller's profile
2. Call `list_classes(start_datetime, end_datetime)` to surface available classes

Booking-enabled flow (after setting `MINDBODY_ALLOW_BOOKINGS=true`):

3. Call `book_client_to_class(client_id, class_id)` to enroll the caller
4. Call `book_appointment(client_id, staff_id, session_type_id, start_datetime)` for 1-on-1 sessions

Payment-enabled flow (after setting `MINDBODY_ALLOW_CHECKOUT=true`):

5. Call `checkout_shopping_cart(client_id, item_id, item_type, quantity)` to process payment

## Safety note: two separate flags for write actions and payment

- `MINDBODY_ALLOW_BOOKINGS` gates the two booking writes (class enrollment + appointment scheduling). Bookings create real reservations on the studio's calendar.
- `MINDBODY_ALLOW_CHECKOUT` gates the payment action. Checkout actually charges the client's payment method. This is intentionally a SEPARATE flag so studio owners can enable AI agent bookings without also enabling AI agent purchasing. Two-step opt-in keeps real money out of an over-eager agent's reach by default.

## Billing note

Since October 1, 2023, Mindbody charges $0.002 per API call in production environments. Operators should cache responses where possible to control billing overhead. This MCP does not cache responses; caching is the operator's responsibility per workflow.

## Architecture

- Public MIT-licensed wrapper around the Mindbody Public API V6
- Async HTTP via `httpx`
- pydantic v2 input validation
- Three-header auth: `Api-Key`, `SiteId`, optional `Authorization` (user token)
- Rate-limit aware (429 returns a clean error)
- Write actions gated by env flag
- Payment action gated by a SEPARATE env flag

## Development

```bash
git clone https://github.com/NoBanks/mindbody-mcp.git
cd mindbody-mcp
pip install -e ".[dev]"
pytest
```

## License

MIT. See [LICENSE](LICENSE).

## Author

Ryan Hammer (NoBanks). Solo founder + engineer. Built this and 15 other MCP servers as part of a sprint to expose AI agent rails for the products and platforms shipping daily. Built mindbody-mcp specifically as a same-day reply to Mindbody's May 28 2026 Bilt Rewards distribution partnership.

- GitHub: [@NoBanks](https://github.com/NoBanks)
- X/Twitter: [@livingagentic](https://x.com/livingagentic)
- Site: [livingagentic.me](https://livingagentic.me), [nohumannearby.com](https://nohumannearby.com)

Open to AI engineering roles, contract or full-time, remote-only.