acuity-scheduling-mcp-2026-complete/README.md

> **🚀 Don't want to self-host?** [Join the waitlist for our fully managed solution →](https://mcpengage.com/acuity)
> 
> Zero setup. Zero maintenance. Just connect and automate.

---

# 🚀 Acuity Scheduling MCP Server — 2026 Complete Version

## 💡 What This Unlocks

**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:

1. **Emergency rescheduling** — "Cancel all appointments for Dr. Smith tomorrow due to illness, send apology notes to clients, find next available slots for each"
2. **Availability intelligence** — "Show me open 60-minute slots next week across all calendars, prioritize Tuesday/Thursday mornings, exclude lunch hours"
3. **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"
4. **Calendar optimization** — "List all appointments this week with no-show history, send reminder SMS 24 hours before, flag high-risk slots"
5. **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:

1. **list_appointments** — Query scheduled appointments with filters (date range, calendar, type, status)
2. **get_appointment** — Get full details for a specific appointment by ID
3. **create_appointment** — Book new appointments with client info and custom intake fields
4. **cancel_appointment** — Cancel appointments with optional notes and no-show marking
5. **list_calendars** — Get all calendars/staff members in your account
6. **get_availability** — Find available time slots by appointment type, calendar, and date
7. **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](https://developers.acuityscheduling.com/reference/overview) (REST)

## 🚀 Quick Start

### Option 1: Claude Desktop (Local)

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

2. **Get your Acuity API credentials:**
   - Log into [Acuity Scheduling](https://acuityscheduling.com/)
   - 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)

3. **Configure Claude Desktop:**
   
   On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   
   On Windows: `%APPDATA%\Claude\claude_desktop_config.json`

   ```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..."
         }
       }
     }
   }
   ```

4. **Restart Claude Desktop**

### Option 2: Deploy to Railway

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/acuity-mcp)

1. Click the button above
2. Set `ACUITY_USER_ID` and `ACUITY_API_KEY` in Railway dashboard
3. Use the Railway URL as your MCP server endpoint

### Option 3: Docker

```bash
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:**
1. Log in to Acuity: https://secure.acuityscheduling.com/login.php
2. Navigate to: Business Settings → Integrations → API
3. 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

```bash
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

```bash
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](https://developers.acuityscheduling.com/reference/overview)** — Official API reference
- **[Acuity Help Center](https://help.acuityscheduling.com/)** — Scheduling guides and tutorials
- **[Squarespace Scheduling](https://www.squarespace.com/scheduling)** — Acuity's parent platform
- **[MCP Protocol Spec](https://modelcontextprotocol.io/)** — How MCP servers work
- **[Claude Desktop Docs](https://claude.ai/desktop)** — Installing and configuring Claude
- **[MCPEngage Platform](https://mcpengine.pages.dev)** — Browse 30+ business MCP servers

## 🤝 Contributing

Contributions are welcome! Please:

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

## 📄 License

MIT License - see [LICENSE](LICENSE) for details

## 🙏 Credits

Built by [MCPEngage](https://mcpengage.com) — AI infrastructure for business software.

Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms including Calendly, Cal.com, SimplyBook.me, and more.

---

**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage).