A comprehensive Model Context Protocol (MCP) server for Acuity Scheduling, providing full API integration with 59 tools and 12 interactive React applications.

Features

🛠️ 59 MCP Tools

Complete CRUD operations across all Acuity Scheduling domains:

Appointments (6 tools): List, get, create, update, cancel, reschedule
Calendars (2 tools): List, get
Appointment Types (5 tools): List, get, create, update, delete
Clients (5 tools): List, get, create, update, delete
Availability (2 tools): Get available dates and times
Blocks (5 tools): List, get, create, update, delete (block out time)
Products (5 tools): List, get, create, update, delete
Certificates (4 tools): List, get, create, delete (gift certificates)
Coupons (5 tools): List, get, create, update, delete
Forms (5 tools): List, get, create, update, delete (intake forms)
Labels (5 tools): List, get, create, update, delete
Packages (5 tools): List, get, create, update, delete
Subscriptions (5 tools): List, get, create, update, delete

🎨 12 React Applications

Modern, dark-themed UI applications:

Appointment Calendar - View and manage daily/weekly appointments
Appointment Detail - Detailed view of individual appointments
Client Directory - Browse and search all clients
Client Detail - Complete client profile with appointment history
Availability Manager - Manage available time slots and blocks
Product Catalog - View and manage products/services
Certificate Viewer - Manage gift certificates
Coupon Manager - Create and track discount coupons
Form Builder - Design and manage intake forms
Analytics Dashboard - Business insights and metrics
Booking Flow - End-to-end appointment booking experience
Schedule Overview - Weekly schedule summary and revenue tracking

Installation

npm install

Configuration

Set the following environment variables:

export ACUITY_USER_ID="your_acuity_user_id"
export ACUITY_API_KEY="your_acuity_api_key"

You can find your User ID and API Key in your Acuity Scheduling account under: Business Settings → Integrations → API

Usage

As MCP Server

Build and start the server:

npm run build
npm start

With Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Development

Watch mode for TypeScript:

npm run dev

Type checking without building:

npm run typecheck

Running React Apps

Each React app can be run independently using Vite:

cd src/ui/react-app/src/apps/appointment-calendar
npm install
npm run dev

Architecture

API Client

The AcuityClient class (src/clients/acuity.ts) handles:

Basic Authentication (userId + API key)
Request/response handling
Error handling
Pagination support

Tools

Each domain has its own tool file in src/tools/:

Standardized input schemas
Proper error handling
Type-safe operations

Type System

Complete TypeScript definitions in src/types/index.ts covering:

Request/response types
API entities
Client configuration

API Reference

Example Tool Calls

List appointments:

{
  "name": "acuity_list_appointments",
  "arguments": {
    "minDate": "2024-01-01",
    "maxDate": "2024-01-31",
    "max": 100
  }
}

Create appointment:

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

Get availability:

{
  "name": "acuity_get_availability_dates",
  "arguments": {
    "appointmentTypeID": 123,
    "month": "2024-01",
    "timezone": "America/New_York"
  }
}

Tech Stack

Server: TypeScript, Node.js, MCP SDK
UI: React 18, TypeScript, Vite, Tailwind CSS
API: Acuity Scheduling REST API v1

License

MIT

Support

For issues or questions:

Acuity API Docs: https://developers.acuityscheduling.com/
MCP Docs: https://modelcontextprotocol.io/

Built with ❤️ for the Model Context Protocol