mcpengine/servers/acuity/README.md

Acuity Scheduling MCP Server

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:

1. Appointment Calendar - View and manage daily/weekly appointments
2. Appointment Detail - Detailed view of individual appointments
3. Client Directory - Browse and search all clients
4. Client Detail - Complete client profile with appointment history
5. Availability Manager - Manage available time slots and blocks
6. Product Catalog - View and manage products/services
7. Certificate Viewer - Manage gift certificates
8. Coupon Manager - Create and track discount coupons
9. Form Builder - Design and manage intake forms
10. Analytics Dashboard - Business insights and metrics
11. Booking Flow - End-to-end appointment booking experience
12. 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