From bd79ed8ec09635148f563fd495e24e620bc64e89 Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 06:59:58 -0500 Subject: [PATCH] =?UTF-8?q?Customize=20Acuity=20Scheduling=20MCP:=20MCPEng?= =?UTF-8?q?ine=E2=86=92MCPEngage,=20add=207-tool=20appointment=20schedulin?= =?UTF-8?q?g=20power=20moves,=20Basic=20Auth,=20real=20API=20v1=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 5 +- README.md | 177 ++++++++++++++++++++++++++++++++++++++------------- package.json | 2 +- 3 files changed, 138 insertions(+), 46 deletions(-) diff --git a/.env.example b/.env.example index 8edaf87..ec7972d 100644 --- a/.env.example +++ b/.env.example @@ -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 diff --git a/README.md b/README.md index 1b9fc41..d0db258 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/package.json b/package.json index 84ea17e..886ee0b 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Acuity Scheduling API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",