This MCP server gives AI direct access to your entire Acuity Scheduling workspace. Instead of clicking through interfaces, you just tell it what you need.

Acuity Scheduling (now Squarespace Scheduling) is the leading appointment booking platform for 250,000+ service businesses—from therapists to consultants to fitness trainers. This MCP server brings scheduling automation into your AI workflow.

🎯 Scheduling Power Moves

Stop context-switching between Claude and Acuity. The AI can directly manage your calendar:

Emergency rescheduling — "Cancel all appointments for Dr. Smith tomorrow due to illness, send apology notes to clients, find next available slots for each"
Availability intelligence — "Show me open 60-minute slots next week across all calendars, prioritize Tuesday/Thursday mornings, exclude lunch hours"
Client booking automation — "Book Sarah Johnson for a 30-minute consultation on March 15 at 2pm, appointment type #4, send her the intake form link"
Calendar optimization — "List all appointments this week with no-show history, send reminder SMS 24 hours before, flag high-risk slots"
Multi-provider coordination — "Which therapist has the most availability this Friday afternoon? Book a new client there for appointment type #12"

🔗 The Real Power: Combining Tools

AI can chain multiple Acuity operations together:

Check availability → Book appointment → Send confirmation → Add to CRM → Set follow-up reminder
Query no-shows → Analyze patterns → Block problem times → Notify staff → Update booking rules
List appointments → Filter by type → Export for billing → Generate revenue reports → Email to accounting

📦 What's Inside

7 powerful API tools covering Acuity's scheduling platform:

list_appointments — Query scheduled appointments with filters (date range, calendar, type, status)
get_appointment — Get full details for a specific appointment by ID
create_appointment — Book new appointments with client info and custom intake fields
cancel_appointment — Cancel appointments with optional notes and no-show marking
list_calendars — Get all calendars/staff members in your account
get_availability — Find available time slots by appointment type, calendar, and date
list_clients — Search clients by name, email, or phone number

All with proper error handling, Basic Auth authentication, and TypeScript types.

API Foundation: Acuity Scheduling API v1 (REST)

🚀 Quick Start

Option 1: Claude Desktop (Local)

Clone and build:

git clone https://github.com/BusyBee3333/Acuity-Scheduling-MCP-2026-Complete.git
cd acuity-scheduling-mcp-2026-complete
npm install
npm run build

Get your Acuity API credentials:
- Log into Acuity Scheduling
- Go to Business Settings → Integrations → API
- Find your User ID (numeric, e.g., 12345678)
- Create or view your API Key (long alphanumeric string)
- Copy both (API access requires User ID + API Key for Basic Auth)

Configure Claude Desktop:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

On Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "acuity": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/acuity-scheduling-mcp-2026-complete/dist/index.js"],
      "env": {
        "ACUITY_USER_ID": "12345678",
        "ACUITY_API_KEY": "abc123def456..."
      }
    }
  }
}

Restart Claude Desktop

Option 2: Deploy to Railway

Click the button above
Set ACUITY_USER_ID and ACUITY_API_KEY in Railway dashboard
Use the Railway URL as your MCP server endpoint

Option 3: Docker

docker build -t acuity-mcp .
docker run -p 3000:3000 \
  -e ACUITY_USER_ID=12345678 \
  -e ACUITY_API_KEY=abc123... \
  acuity-mcp

🔐 Authentication

Acuity uses HTTP Basic Authentication (API v1):

Header: Authorization: Basic BASE64(userId:apiKey)
Format: User ID (numeric) + API Key (alphanumeric string)
Permissions: Full account access (read/write appointments, calendars, clients)
Rate limits: 600 calls per 5-minute window per account

Getting credentials:

Log in to Acuity: https://secure.acuityscheduling.com/login.php
Navigate to: Business Settings → Integrations → API
Copy your User ID and API Key (create one if needed)

The MCP server handles Basic Auth automatically—just set ACUITY_USER_ID and ACUITY_API_KEY.

🎯 Example Prompts for Scheduling Managers

Once connected to Claude, use natural language. Here are real scheduling workflows:

Appointment Management

"List all appointments for tomorrow, show me client names, times, and appointment types"
"Book a new appointment for Michael Chen on March 20 at 3pm, appointment type #5, email michael@example.com"
"Cancel appointment #987654, reason: client rescheduled, mark as no-show: false"

Availability Queries

"What 30-minute slots are available next Tuesday for appointment type #12?"
"Check Dr. Johnson's calendar (calendar #3) for openings this week after 2pm"
"Find the first available 60-minute slot across all calendars next month"

Client Operations

"Search for client 'Sarah Williams', show all her past appointments"
"Find all clients with '@gmail.com' emails who booked in the last 7 days"
"List clients who have booked more than 3 appointments this year"

Calendar Coordination

"Show me all calendars, how many appointments does each have this week?"
"Which staff member has the lightest schedule this Friday afternoon?"
"List appointments for calendar #2 between March 1-15, filter out cancellations"

Bulk Operations

"Export all appointments from last month as JSON for billing"
"Cancel all appointments for calendar #5 next Tuesday (staff out sick)"
"Find all appointments with appointment type #8, how many are no-shows?"

Business Intelligence

"Show me appointment volume by day for the past 2 weeks"
"Which appointment types are booked most frequently? What's the average duration?"
"List all appointments that were created within 24 hours of their start time (last-minute bookings)"

🛠️ Development

Prerequisites

Node.js 18+
npm or yarn
Acuity Scheduling account (free trial or paid)

Setup

git clone https://github.com/BusyBee3333/Acuity-Scheduling-MCP-2026-Complete.git
cd acuity-scheduling-mcp-2026-complete
npm install
cp .env.example .env
# Edit .env with your Acuity User ID and API Key
npm run build
npm start

Testing

npm test                  # Run all tests
npm run test:watch        # Watch mode
npm run test:coverage     # Coverage report

Project Structure

acuity-scheduling-mcp-2026-complete/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript
├── package.json
├── tsconfig.json
└── .env.example

🐛 Troubleshooting

"Authentication failed" or "401 Unauthorized"

Verify both User ID and API Key are correct
User ID should be numeric (e.g., 12345678, not "user123")
API Key is case-sensitive
Check that API access is enabled: Business Settings → Integrations → API

"Rate limit exceeded"

Acuity limits: 600 API calls per 5-minute window
Wait 5 minutes before retrying
Use pagination and filters to reduce call volume

"Tools not appearing in Claude"

Restart Claude Desktop after updating config
Check that the path in claude_desktop_config.json is absolute (not relative)
Verify the build completed: ls dist/index.js
Check Claude Desktop logs: tail -f ~/Library/Logs/Claude/mcp*.log

"Invalid appointment type ID" or "Calendar not found"

Appointment type IDs and calendar IDs are numeric
Get valid IDs: "List all calendars" or "What appointment types are configured?"
Note: Some accounts have 1 calendar, others have multiple

"Cannot book appointment: slot unavailable"

Check availability first: "Show me open slots for appointment type #X on [date]"
Verify the calendar is accepting bookings (not blocked)
Ensure the appointment type is active and published

"Missing required field: email"

New appointments require: datetime, appointmentTypeID, firstName, lastName, email
Phone number is optional but recommended
Custom intake fields go in the fields array parameter

📖 Resources

Acuity API v1 Docs — Official API reference
Acuity Help Center — Scheduling guides and tutorials
Squarespace Scheduling — Acuity's parent platform
MCP Protocol Spec — How MCP servers work
Claude Desktop Docs — Installing and configuring Claude
MCPEngage Platform — Browse 30+ business MCP servers

🤝 Contributing

Contributions are welcome! Please:

Fork the repo
Create a feature branch (git checkout -b feature/calendar-sync)
Commit your changes (git commit -m 'Add Google Calendar sync tool')
Push to the branch (git push origin feature/calendar-sync)
Open a Pull Request

📄 License

MIT License - see LICENSE for details

🙏 Credits

Built by MCPEngage — AI infrastructure for business software.

Want more MCP servers? Check out our full catalog covering 30+ business platforms including Calendly, Cal.com, SimplyBook.me, and more.

Questions? Open an issue or join our Discord community.