zenoti-mcp-server

Zenoti MCP Server

A Model Context Protocol (MCP) server that provides intelligent access to the Zenoti spa/wellness management API. Designed for AI agents to efficiently manage appointments, guests, services, and billing workflows.

Hosted version available

Do not want to manage credentials, hosting, and updates yourself? DOCK is the managed version of this server: encrypted per-practice auth, audit logs, draft-first write actions, and a workflow library. Founding practices lock lifetime pricing: Front Desk $49/mo (Zenoti), Billing Desk $99/mo (Tebra, BAA included), Full Practice $129/mo (both). https://dockhq.vercel.app

Features

Workflow-Centric Tools

• Complete Service Booking: Single tool handles the entire 4-step booking flow
• Guest Lifecycle Management: Create, search, update guests with smart defaults
• Appointment Management: Check-in, status updates, and progress tracking
• Invoice & Payment: Retrieve, confirm, and close invoices with proper error handling
• Forms & Feedback: List forms, retrieve data, and submit feedback

Agent-Optimized Design

• Context-Efficient Responses: Returns only essential information by default
• Smart Error Messages: Guides agents toward correct usage patterns
• Workflow Consolidation: Combines related operations into single tools
• Human-Readable Outputs: Uses names over IDs, dates in readable format

Installation

1. Clone the repository:

git clone https://github.com/yourusername/zenoti-mcp-server.git
cd zenoti-mcp-server

1. Install dependencies:

npm install

1. Configure environment variables:

cp .env.example .env
# Edit .env with your Zenoti API credentials

1. Build the server:

npm run build

Configuration

Environment Variables

• ZENOTI_API_KEY: Your Zenoti API key (required)
• ZENOTI_API_URL: Zenoti API base URL (default: https://api.zenoti.com)
• ZENOTI_CENTER_ID: Default center ID for operations
• ZENOTI_ORG_ID: Your organization ID

Obtaining API Credentials

1. Log into Zenoti Admin
2. Navigate to: Admin > Setup > Apps (organization level)
3. Create a new backend app
4. Assign necessary module permissions (avoid global permissions)
5. Copy the API key (valid for 1 year)

Usage

Running the Server

# Development mode with auto-reload
npm run dev

# Production mode
npm start

# Test the server with example client
npm test

Connecting from Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "zenoti": {
      "command": "node",
      "args": ["/path/to/zenoti-mcp-server/dist/index.js"],
      "env": {
        "ZENOTI_API_KEY": "your_api_key",
        "ZENOTI_API_URL": "https://api.zenoti.com",
        "ZENOTI_CENTER_ID": "your_center_id"
      }
    }
  }
}

Available Tools

Service Booking

book_service

Complete 4-step service booking workflow in a single tool.

Parameters:

• guest_id (required): Guest ID or search query
• service_id (required): Service ID or name
• date (required): Appointment date (YYYY-MM-DD)
• time (optional): Preferred time (HH:MM)
• therapist_id (optional): Therapist ID or name
• notes (optional): Booking notes
• pay_later (optional): Skip payment (default: true)

Example: ``json { "guest_id": "john.doe@email.com", "service_id": "Deep Tissue Massage", "date": "2025-11-15", "time": "14:00" } ``

Guest Management

search_guests

Search for guests by name, email, or phone.

Parameters:

• query (required): Search query
• limit (optional): Max results (default: 10)

create_guest

Create a new guest profile.

Parameters:

• first_name (required)
• last_name (required)
• email (optional)
• phone (optional)
• gender (optional)
• date_of_birth (optional)

Appointment Management

list_appointments

List appointments with filters.

Parameters:

• start_date (required): Start date (YYYY-MM-DD)
• end_date (optional): End date (default: start_date)
• status (optional): Filter by status
• guest_id (optional): Filter by guest
• limit (optional): Max results (default: 50)

check_in_appointment

Check in a guest for their appointment.

Parameters:

• appointment_id (required): Appointment or group ID

update_appointment_status

Update appointment status (confirm, cancel, no-show).

Parameters:

• appointment_id (required)
• status (required): "confirmed", "cancelled", "no_show"
• reason (optional): Cancellation reason

Invoice & Payment

get_invoice

Retrieve invoice details.

Parameters:

• invoice_id (required)
• include_details (optional): Include line items (default: true)

close_invoice

Process payment and close invoice.

Parameters:

• invoice_id (required)
• payment_method (optional): Payment type
• amount (optional): Payment amount

Forms & Feedback

list_appointment_forms

Get forms for an appointment.

Parameters:

• appointment_id (required)

submit_feedback

Submit guest feedback for appointment.

Parameters:

• appointment_id (required)
• rating (required): 1-5 or 1-10
• comments (optional)

Error Handling

The server provides actionable error messages to guide agents:

{
  "error": "No available slots found",
  "suggestion": "Try a different date or remove therapist preference",
  "alternatives": ["2025-11-16", "2025-11-17"]
}

Rate Limiting

The server implements intelligent rate limiting:

• Automatic retry with exponential backoff
• Rate limit status in responses
• Suggestions for reducing API calls

Development

Project Structure

zenoti-mcp-server/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── zenoti-client.ts   # Zenoti API client
│   ├── tools/             # Tool implementations
│   │   ├── booking.ts     # Service booking tools
│   │   ├── guests.ts      # Guest management tools
│   │   ├── appointments.ts # Appointment tools
│   │   └── invoices.ts    # Invoice tools
│   ├── utils/             # Shared utilities
│   │   ├── errors.ts      # Error handling
│   │   ├── formatters.ts  # Response formatting
│   │   └── validators.ts  # Input validation
│   └── test-client.ts     # Test client
├── package.json
├── tsconfig.json
└── README.md

Testing

Run the test client to verify functionality:

npm test

The test client demonstrates:

• Service booking workflow
• Guest search and creation
• Appointment management
• Error handling

Best Practices

For AI Agents

1. Use search before create: Always search for existing guests before creating
2. Handle partial matches: Guest search returns fuzzy matches
3. Respect rate limits: Use suggested delays between requests
4. Check availability first: Query slots before attempting bookings
5. Use human-readable inputs: Names work as well as IDs

For Developers

1. Environment-specific apps: Create separate Zenoti apps for dev/staging/prod
2. Minimal permissions: Grant only necessary module permissions
3. Token refresh: Implement token refresh for long-running sessions
4. Error logging: Monitor failed requests for API issues
5. Webhook integration: Consider webhooks for real-time updates

Troubleshooting

Common Issues

1. API Key Authorization Denied (Error 602)

• Verify API key is correct and not expired
• Check app has necessary permissions in Zenoti
• Ensure using correct center_id

1. No Available Slots

• Check service is bookable online
• Verify therapist works on requested date
• Try without therapist preference

1. Guest Not Found

• Search uses fuzzy matching
• Try partial name or email
• Check guest exists in correct center

License

MIT License - See LICENSE file for details

Support

For issues or questions:

• GitHub Issues: zenoti-mcp-server/issues
• Zenoti API Docs: docs.zenoti.com
• MCP Protocol: modelcontextprotocol.io