jake/acuity-scheduling-mcp-2026-complete
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Customize Acuity Scheduling MCP: MCPEngine→MCPEngage, add 7-tool appointment scheduling power moves, Basic Auth, real API v1 docs

Browse Source
This commit is contained in:
Jake Shore 2026-02-02 06:59:58 -05:00
parent 47647f8636
commit bd79ed8ec0
3 changed files with 138 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.env.example
View File

@ -1,2 +1,3 @@
# Acuity Scheduling API Credentials
ACUITY_SCHEDULING_API_KEY=your-api-key-here
# Acuity Scheduling API Credentials (Basic Auth)
ACUITY_USER_ID=your-user-id-here
ACUITY_API_KEY=your-api-key-here

177
README.md
View File

@ -10,28 +10,41 @@
**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-Native Power Moves
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.
The AI can directly control your Acuity Scheduling account with natural language:
### 🎯 Scheduling Power Moves
- **Smart automation** — Complex workflows in plain English
- **Data intelligence** — Query, analyze, and export your Acuity Scheduling data
- **Rapid operations** — Bulk actions that would take hours manually
- **Cross-platform integration** — Combine Acuity Scheduling with other tools seamlessly
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 Scheduling operations together:
AI can chain multiple Acuity operations together:
- Query data → Filter results → Generate reports
- Search records → Update fields → Notify team
- Analyze metrics → Create tasks → Schedule follow-ups
- 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
**45 API tools** covering the entire Acuity Scheduling platform (Scheduling).
**7 powerful API tools** covering Acuity's scheduling platform:
All with proper error handling, automatic authentication, and TypeScript types.
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
@ -45,7 +58,12 @@ All with proper error handling, automatic authentication, and TypeScript types.
npm run build
```
2. **Get your Acuity Scheduling API credentials** (see Authentication section below)
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:**
@ -58,9 +76,10 @@ All with proper error handling, automatic authentication, and TypeScript types.
"mcpServers": {
"acuity": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/acuity-mcp/dist/index.js"],
"args": ["/ABSOLUTE/PATH/TO/acuity-scheduling-mcp-2026-complete/dist/index.js"],
"env": {
"ACUITY_SCHEDULING_API_KEY": "your-api-key-here"
"ACUITY_USER_ID": "12345678",
"ACUITY_API_KEY": "abc123def456..."
}
}
}
@ -74,7 +93,7 @@ All with proper error handling, automatic authentication, and TypeScript types.
[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/acuity-mcp)
1. Click the button above
2. Set your Acuity Scheduling API credentials in Railway dashboard
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
@ -82,32 +101,67 @@ All with proper error handling, automatic authentication, and TypeScript types.
```bash
docker build -t acuity-mcp .
docker run -p 3000:3000 \
-e ACUITY_SCHEDULING_API_KEY=your-key \
-e ACUITY_USER_ID=12345678 \
-e ACUITY_API_KEY=abc123... \
acuity-mcp
```
## 🔐 Authentication
See the official [Acuity Scheduling API documentation](https://docs.acuity.com) for authentication details.
**Acuity uses HTTP Basic Authentication** (API v1):
The MCP server handles token refresh automatically.
- **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
## 🎯 Example Prompts
**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)
Once connected to Claude, you can use natural language. Examples:
The MCP server handles Basic Auth automatically—just set `ACUITY_USER_ID` and `ACUITY_API_KEY`.
- *"Show me recent activity in Acuity Scheduling"*
- *"Create a new record with these details..."*
- *"Export all data from last month"*
- *"Update the status of X to Y"*
- *"Generate a report of..."*
## 🎯 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 with API access
- Acuity Scheduling account (free trial or paid)
### Setup
@ -116,7 +170,7 @@ 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 Scheduling credentials
# Edit .env with your Acuity User ID and API Key
npm run build
npm start
```
@ -129,32 +183,69 @@ 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"
- Verify your API credentials are correct
- Check that your API key hasn't been revoked
- Ensure you have the necessary permissions
### "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
- Verify the build completed successfully (`dist/index.js` exists)
- 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 Scheduling API Documentation](https://docs.acuity.com)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Desktop Documentation](https://claude.ai/desktop)
- **[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/amazing-tool`)
3. Commit your changes (`git commit -m 'Add amazing tool'`)
4. Push to the branch (`git push origin feature/amazing-tool`)
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
@ -163,10 +254,10 @@ MIT License - see [LICENSE](LICENSE) for details
## 🙏 Credits
Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software.
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.
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/mcpengine).
**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage).

2
package.json
View File

@ -4,7 +4,7 @@
"description": "MCP server for Acuity Scheduling API - 2026 Complete Version",
"type": "module",
"main": "dist/index.js",
"author": "MCPEngine <hello@mcpengage.com>",
"author": "MCPEngage <hello@mcpengage.com>",
"license": "MIT",
"repository": {
"type": "git",