Mindbody MCP Server

Interaja com a API Mindbody para gerenciar estúdios de fitness e bem-estar.

GitHub
9
Experimente este MCPPatrocinado

Documentação

🧘 Mindbody MCP Server

npm version CI License: MIT MCP SDK

Um servidor abrangente do Model Context Protocol (MCP) que fornece aos assistentes de IA acesso completo à API Mindbody para gerenciamento de estúdios de fitness e bem-estar. Perfeito para estúdios de yoga, estúdios de pilates, academias e centros de bem-estar.

✨ Recursos

  • Mais de 50 ferramentas cobrindo todos os aspectos das operações do estúdio
  • Gerenciamento completo de aulas - Visualize horários, reserve clientes, gerencie listas de espera, professores substitutos
  • Gerenciamento de clientes - Adicione/atualize clientes, acompanhe visitas, assinaturas e saldos
  • Vendas e comércio - Processe pagamentos, venda pacotes, assinaturas e produtos de varejo
  • Gerenciamento de equipe - Visualize horários, gerencie compromissos, acompanhe disponibilidade
  • Suporte a múltiplas unidades - Gerencie várias unidades do estúdio de forma integrada
  • Alto desempenho - Construído no runtime Bun com cache inteligente
  • Type-Safe - Suporte completo a TypeScript com tipos abrangentes
  • Suporte a transporte duplo - STDIO para desenvolvimento local, SSE para implantação em produção

🚀 Início rápido

Instalação com npx (Node.js)

# Run directly without installation
npx @vespo92/mindbody-mcp

# Or install globally
npm install -g @vespo92/mindbody-mcp

Instalação com bunx (Bun - 4x mais rápido)

# Run directly without installation  
bunx @vespo92/mindbody-mcp

# Or install globally with Bun
bun install -g @vespo92/mindbody-mcp

Instalar a partir do GitHub

# Using npx
npx github:vespo92/MindbodyMCP

# Using bunx (recommended for performance)
bunx github:vespo92/MindbodyMCP

# Or clone and run locally
git clone https://github.com/vespo92/MindbodyMCP.git
cd MindbodyMCP
bun install # or npm install
bun run start # or npm start

📋 Pré-requisitos

  • Node.js 18+ ou Bun 1.0+
  • Credenciais da API Mindbody (API Key, Site ID, credenciais de origem)
  • Claude Desktop ou qualquer cliente compatível com MCP

⚙️ Configuração

1. Obtenha as credenciais da API Mindbody

  1. Cadastre-se em uma Conta de desenvolvedor Mindbody
  2. Crie um novo aplicativo para obter suas credenciais de API
  3. Anote seu Site ID (use -99 para testes em sandbox)

2. Defina as variáveis de ambiente

Crie um arquivo .env na raiz do seu projeto:

# Copy the example file
cp .env.example .env

# Edit with your credentials
MINDBODY_API_KEY=your_api_key_here
MINDBODY_SITE_ID=-99  # Your site ID
MINDBODY_SOURCE_NAME=your_source_name
MINDBODY_SOURCE_PASSWORD=your_source_password

# Optional settings
MINDBODY_API_URL=https://api.mindbodyonline.com/public/v6
CACHE_TTL_MINUTES=5
MCP_SERVER_NAME=mindbody-mcp
MCP_SERVER_VERSION=2.0.0

3. Configure o Claude Desktop

Adicione à configuração do seu Claude Desktop:

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

{
  "mcpServers": {
    "mindbody": {
      "command": "bunx",
      "args": ["@vespo92/mindbody-mcp"],
      "env": {
        "MINDBODY_API_KEY": "your_api_key",
        "MINDBODY_SITE_ID": "-99",
        "MINDBODY_SOURCE_NAME": "your_source_name",
        "MINDBODY_SOURCE_PASSWORD": "your_source_password"
      }
    }
  }
}

Ou use o repositório do GitHub diretamente:

{
  "mcpServers": {
    "mindbody": {
      "command": "bunx",
      "args": ["github:vespo92/MindbodyMCP"],
      "env": {
        "MINDBODY_API_KEY": "your_api_key",
        "MINDBODY_SITE_ID": "-99",
        "MINDBODY_SOURCE_NAME": "your_source_name",
        "MINDBODY_SOURCE_PASSWORD": "your_source_password"
      }
    }
  }
}

🛠️ Ferramentas disponíveis

O servidor fornece mais de 50 ferramentas em 7 categorias:

📅 Gerenciamento de aulas

  • getClasses - Visualize todas as aulas com filtros
  • getClassDescriptions - Liste os tipos de aula
  • getClassSchedules - Visualize horários recorrentes
  • addClientToClass - Reserve clientes em aulas
  • removeClientFromClass - Cancele reservas
  • getWaitlistEntries - Gerencie listas de espera
  • substituteClassTeacher - Lide com substituições

👥 Gerenciamento de clientes

  • getClients - Pesquise e recupere clientes
  • addClient - Registre novos clientes
  • updateClient - Atualize informações do cliente
  • getClientVisits - Visualize histórico de presença
  • getClientMemberships - Verifique assinaturas ativas
  • addClientArrival - Faça check-in de clientes
  • getClientAccountBalances - Visualize saldos de conta
  • getClientContracts - Visualize contratos

💰 Vendas e comércio

  • getServices - Visualize serviços disponíveis
  • getPackages - Liste pacotes de aulas
  • getProducts - Navegue por produtos de varejo
  • getContracts - Visualize opções de assinatura
  • checkoutShoppingCart - Processe compras
  • purchaseContract - Venda assinaturas

🏢 Site e unidades

  • getSites - Obtenha informações do negócio
  • getLocations - Liste todas as unidades
  • getPrograms - Visualize programas oferecidos
  • getResources - Gerencie recursos
  • getSessionTypes - Liste tipos de sessão
  • getStaff - Visualize todos os membros da equipe
  • getTeacherSchedule - Horários dos professores

📆 Compromissos

  • getStaffAppointments - Visualize compromissos
  • addAppointment - Reserve compromissos
  • updateAppointment - Modifique compromissos
  • getBookableItems - Encontre horários disponíveis
  • getActiveSessionTimes - Verifique disponibilidade
  • getScheduleItems - Visualize horários

🎓 Inscrições

  • getEnrollments - Visualize cursos/oficinas
  • addClientToEnrollment - Inscreva-se em cursos
  • getClientEnrollments - Visualize inscrições de clientes

💬 Exemplo de uso no Claude

Depois de configurado, você pode perguntar ao Claude:

"Show me today's yoga classes"
"Book Sarah Johnson into the 6pm Vinyasa class"
"Who's on the waitlist for tomorrow's Hot Yoga?"
"Add a new client named Jennifer Wilson"
"What's Michael's attendance this month?"
"Process a 10-class package purchase for Amy"
"Find a substitute for Maria's Thursday class"

🏗️ Desenvolvimento

Desenvolvimento local

# Clone the repository
git clone https://github.com/vespo92/MindbodyMCP.git
cd MindbodyMCP

# Install dependencies
bun install  # or npm install

# Run in development mode
bun run dev  # or npm run dev

# Run tests
bun test  # or npm test

# Build for production
bun run build  # or npm run build

Estrutura do projeto

MindbodyMCP/
├── src/
│   ├── index.ts           # Main server entry point
│   ├── api/               # API client and auth
│   ├── tools/             # Tool implementations
│   ├── types/             # TypeScript types
│   ├── cache/             # Caching layer
│   └── utils/             # Utility functions
├── tests/                 # Test files
├── .github/workflows/     # CI/CD pipelines
└── CLAUDE.md             # Detailed documentation

🌐 Implantação SSE (produção)

O servidor suporta transporte SSE (Server-Sent Events) para implantação em produção, permitindo clientes baseados na web e acesso remoto.

Início rápido com SSE

# Start with SSE transport
bun run start:sse

# Or with environment variable
MCP_TRANSPORT=sse bun start

# With custom port
bun run src/index.ts --transport sse --port 8080

Implantação com Docker

# Using Docker Compose
docker-compose up -d

# Or manually
docker build -t mindbody-mcp .
docker run -d -p 3000:3000 -e MCP_TRANSPORT=sse mindbody-mcp

Configuração de produção

Configure por meio de variáveis de ambiente:

  • MCP_TRANSPORT=sse - Ativa o transporte SSE
  • MCP_PORT=3000 - Porta do servidor
  • MCP_HOST=0.0.0.0 - Host do servidor
  • MCP_CORS_ORIGIN=https://yourdomain.com - Configuração de CORS
  • MCP_SSL_CERT=/path/to/cert.pem - Certificado SSL (opcional)
  • MCP_SSL_KEY=/path/to/key.pem - Chave privada SSL (opcional)

Endpoints

  • /health - Endpoint de verificação de saúde
  • /info - Informações do servidor
  • /sse - Fluxo de eventos SSE para comunicação MCP

Para instruções detalhadas de implantação, consulte o Guia de implantação SSE.

🧪 Testes

# Run all tests
bun test

# Test SSE connection
bun run test:sse

# Test specific tool
bun run test:tool

# Run benchmarks
bun run benchmark

# Type checking
bun run typecheck

📦 Publicação

O pacote está disponível em:

🔒 Segurança

  • As credenciais da API são armazenadas com segurança por meio de variáveis de ambiente
  • Autenticação OAuth 2.0 com renovação automática de token
  • Nenhuma credencial é registrada ou exposta
  • Auditorias de segurança regulares via GitHub Actions

⚡ Desempenho

  • Runtime Bun: inicialização 4x mais rápida que Node.js
  • Cache inteligente: cache de 5 minutos para dados dinâmicos, 60 minutos para estáticos
  • Tentativa automática: backoff exponencial para solicitações com falha
  • Limite de taxa: respeita o limite de 2000 solicitações/hora da Mindbody

🤝 Contribuições

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

  1. Faça um fork do repositório
  2. Crie sua branch de recurso (git checkout -b feature/AmazingFeature)
  3. Faça commit das suas alterações (git commit -m 'Add some AmazingFeature')
  4. Envie para a branch (git push origin feature/AmazingFeature)
  5. Abra um Pull Request

📄 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

🙏 Agradecimentos

  • Mindbody API por fornecer APIs abrangentes para estúdios de fitness
  • Anthropic MCP SDK pelo Model Context Protocol
  • Bun pelo runtime JavaScript extremamente rápido

📞 Suporte

🚀 Roadmap

  • Suporte a webhooks para atualizações em tempo real
  • Ferramentas avançadas de relatórios e análises
  • Sincronização de múltiplas unidades
  • Recomendações com IA
  • Integração com aplicativo móvel
  • Camada de API GraphQL
Feito com ❤️ para estúdios de yoga e centros de bem-estar em todo o mundo