mcpengine/servers/acuity-scheduling

Acuity Scheduling MCP Server

A comprehensive Model Context Protocol (MCP) server for Acuity Scheduling API integration.

Features

40+ Tools Across 10 Categories

• Appointments (8 tools): List, get, create, update, cancel, reschedule, list types, get type
• Availability (4 tools): Get dates, get times, get classes, check availability
• Clients (5 tools): List, get, create, update, delete
• Calendars (4 tools): List, get, create, update
• Products (6 tools): List products by type (add-ons, packages, subscriptions, gift certificates)
• Forms (3 tools): List forms, get fields, get intake form responses
• Labels (5 tools): List, create, delete, add to appointment, remove from appointment
• Webhooks (3 tools): List, create, delete
• Coupons (5 tools): List, get, create, update, delete
• Blocks (3 tools): List, create, delete time blocks

14 Interactive MCP Apps

1. Appointment Dashboard - Overview dashboard with stats and upcoming appointments
2. Appointment Detail - Detailed view of individual appointments
3. Appointment Grid - Filterable table view of all appointments
4. Availability Calendar - Interactive calendar showing available time slots
5. Client Directory - Searchable directory of all clients
6. Client Detail - Comprehensive client profiles with appointment history
7. Calendar Manager - Manage staff calendars and settings
8. Product Catalog - Browse products, packages, and add-ons
9. Form Responses - View and manage intake form submissions
10. Label Manager - Create and manage appointment labels
11. Coupon Manager - Create and track promotional coupons
12. Booking Flow - Interactive multi-step booking interface
13. Schedule Overview - Week-view schedule across all calendars
14. Blocked Time Manager - Manage blocked time slots and staff availability

Installation

npm install
npm run build

Configuration

Create a .env file with your Acuity Scheduling credentials:

# Required
ACUITY_USER_ID=your_user_id
ACUITY_API_KEY=your_api_key

# Optional (for OAuth2)
ACUITY_OAUTH2_TOKEN=your_oauth2_token

Getting API Credentials

1. Log in to your Acuity Scheduling account
2. Go to Business Settings → Integrations → API
3. Enable API access and copy your User ID and API Key

Usage

As MCP Server

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "acuity-scheduling": {
      "command": "node",
      "args": ["/path/to/acuity-scheduling/dist/main.js"],
      "env": {
        "ACUITY_USER_ID": "your_user_id",
        "ACUITY_API_KEY": "your_api_key"
      }
    }
  }
}

Standalone

npm start

API Reference

Authentication

The server supports two authentication methods:

1. Basic Auth (recommended): Uses User ID and API Key
2. OAuth2: Uses OAuth2 access token

Tool Examples

List Appointments

{
  "tool": "acuity_list_appointments",
  "arguments": {
    "minDate": "2024-01-01",
    "maxDate": "2024-01-31",
    "calendarID": 1
  }
}

Create Appointment

{
  "tool": "acuity_create_appointment",
  "arguments": {
    "appointmentTypeID": 1,
    "datetime": "2024-01-15T10:00:00",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "555-1234"
  }
}

Get Availability

{
  "tool": "acuity_get_availability_times",
  "arguments": {
    "appointmentTypeID": 1,
    "date": "2024-01-15"
  }
}

MCP Apps

Access interactive apps through MCP resources:

• acuity://apps/appointment-dashboard
• acuity://apps/availability-calendar
• acuity://apps/client-directory
• And 11 more...

Each app provides a rich, interactive UI for managing different aspects of your Acuity Scheduling account.

Architecture

src/
├── clients/
│   └── acuity.ts          # API client with auth & pagination
├── tools/
│   ├── appointments-tools.ts
│   ├── availability-tools.ts
│   ├── clients-tools.ts
│   ├── calendars-tools.ts
│   ├── products-tools.ts
│   ├── forms-tools.ts
│   ├── labels-tools.ts
│   ├── webhooks-tools.ts
│   ├── coupons-tools.ts
│   └── blocks-tools.ts
├── types/
│   └── index.ts           # TypeScript type definitions
├── ui/
│   └── react-app/         # 14 interactive MCP apps
├── server.ts              # MCP server implementation
└── main.ts                # Entry point

Development

# Build
npm run build

# Watch mode
npm run dev

# Run server
npm start

Error Handling

The server includes comprehensive error handling:

• API rate limit detection
• Network error retries
• Invalid credential detection
• Missing required parameters validation

Rate Limits

Acuity Scheduling API has rate limits. The client handles:

• Automatic pagination for large result sets
• Error responses with status codes
• Request throttling (if needed)

Support

For issues or questions:

• Acuity Scheduling API Documentation: https://developers.acuityscheduling.com/
• MCP Documentation: https://modelcontextprotocol.io/

License

MIT

Version

1.0.0