MindbodyMCP

vespo92/MindbodyMCP

3.2

If you are the rightful owner of MindbodyMCP and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Mindbody MCP Server is a high-performance server designed to facilitate interactions between AI assistants and the Mindbody API, specifically for managing fitness and wellness studios.

Mindbody MCP Server

A high-performance Model Context Protocol (MCP) server that enables AI assistants to interact with the Mindbody API for fitness and wellness studio management.

๐Ÿš€ Features

  • โšก Lightning Fast: Built with Bun for 4x faster startup times
  • ๐Ÿ” Secure Authentication: OAuth 2.0 with automatic token refresh
  • ๐Ÿ’พ Smart Caching: Intelligent caching to respect API rate limits
  • ๐Ÿ›ก๏ธ Robust Error Handling: Graceful failures with clear error messages
  • ๐Ÿ“Š Rich Data: Comprehensive schedule data with summaries and insights
  • ๐Ÿ”„ Auto-Retry: Built-in retry logic for transient failures

๐Ÿ“ฆ Installation

Prerequisites

  • Bun (recommended) or Node.js 18+
  • Mindbody API credentials
  • Claude Desktop

Quick Start

# Clone the repository
git clone https://github.com/yourusername/mindbody-mcp.git
cd mindbody-mcp

# Install dependencies (using Bun)
bun install

# Copy environment variables
cp .env.example .env

# Edit .env with your Mindbody credentials
# Then run the development server
bun run dev

Using Node.js Instead

# Switch to Node.js configuration
./switch.bat node  # Windows
# or manually: cp package.node.json package.json

# Install and build
npm install
npm run build
npm start

โš™๏ธ Configuration

Environment Variables

Create a .env file with your Mindbody credentials:

# Required
MINDBODY_API_KEY=your_api_key_here
MINDBODY_SITE_ID=-99
MINDBODY_SOURCE_NAME=your_source_name
MINDBODY_SOURCE_PASSWORD=your_source_password

# Optional
MINDBODY_API_URL=https://api.mindbodyonline.com/public/v6
CACHE_TTL_MINUTES=5
RATE_LIMIT_BUFFER=100

Claude Desktop Integration

Add to your Claude Desktop configuration:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mindbody": {
      "command": "bun",
      "args": ["run", "C:\\path\\to\\mindbody-mcp\\src\\index.ts"],
      "env": {
        "MINDBODY_API_KEY": "your_api_key",
        "MINDBODY_SITE_ID": "-99",
        "MINDBODY_SOURCE_NAME": "your_source_name",
        "MINDBODY_SOURCE_PASSWORD": "your_source_password"
      }
    }
  }
}

๐Ÿ› ๏ธ Available Tools

getTeacherSchedule

Retrieves a teacher's class schedule for any date range.

Parameters:

  • teacherName (string, required): The teacher's full name
  • startDate (string, optional): Start date in YYYY-MM-DD format
  • endDate (string, optional): End date in YYYY-MM-DD format

Example Usage:

"Get Alexia Bauer's schedule for this week"
"Show me John Smith's classes for next Monday"
"What is Sarah teaching between March 15-22?"

Coming Soon

  • ๐Ÿ“… getClassSchedule - View all classes by date/location
  • ๐Ÿ”„ createSubstitution - AI-powered substitute teacher matching
  • ๐Ÿ“ updateEvent - Modify class details and descriptions
  • ๐Ÿ‘ฅ getClientBookings - View and manage client reservations
  • ๐Ÿ’ฐ generateReports - Financial and attendance analytics

๐Ÿ—๏ธ Project Structure

mindbody-mcp/
โ”œโ”€โ”€ src/
โ”‚   โ”œโ”€โ”€ index.ts              # MCP server entry point
โ”‚   โ”œโ”€โ”€ api/
โ”‚   โ”‚   โ”œโ”€โ”€ auth.ts          # OAuth token management
โ”‚   โ”‚   โ””โ”€โ”€ client.ts        # Axios client with retry logic
โ”‚   โ”œโ”€โ”€ cache/
โ”‚   โ”‚   โ””โ”€โ”€ index.ts         # In-memory caching system
โ”‚   โ”œโ”€โ”€ tools/
โ”‚   โ”‚   โ””โ”€โ”€ teacherSchedule.ts
โ”‚   โ”œโ”€โ”€ types/
โ”‚   โ”‚   โ””โ”€โ”€ mindbody.ts      # TypeScript type definitions
โ”‚   โ””โ”€โ”€ utils/
โ”‚       โ””โ”€โ”€ dates.ts         # Date helper functions
โ”œโ”€โ”€ .env.example             # Environment variable template
โ”œโ”€โ”€ bunfig.toml             # Bun configuration
โ”œโ”€โ”€ Claude.md               # AI assistant instructions
โ””โ”€โ”€ package.json            # Project dependencies

๐Ÿงช Testing

# Test the teacher schedule tool
bun run test:tool

# Run performance benchmark
bun run benchmark

# Compare Bun vs Node.js performance
./switch.bat benchmark

๐Ÿค Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Workflow

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Adding New Tools

  1. Create a new file in src/tools/
  2. Follow the pattern from teacherSchedule.ts
  3. Add types to src/types/mindbody.ts
  4. Register in src/index.ts
  5. Update documentation

๐Ÿ“Š Performance

Using Bun provides significant performance improvements:

MetricNode.jsBunImprovement
Cold Start~800ms~200ms4x faster
First API Call~1200ms~400ms3x faster
Memory Usage~50MB~30MB40% less

๐Ÿ”’ Security

  • OAuth 2.0 authentication with automatic token refresh
  • Environment variables for sensitive configuration
  • No credentials stored in code
  • Automatic token expiration handling
  • Input validation on all user inputs

๐Ÿ“ License

This project is licensed under the MIT License - see the file for details.

๐Ÿ™ Acknowledgments

  • Anthropic for the MCP specification
  • Mindbody for their comprehensive API
  • Bun for the incredible runtime performance

๐Ÿ“ž Support


Built with โค๏ธ for the fitness and wellness community