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

.env.example

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

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
+Stop context-switching between Claude and Acuity. The AI can directly manage your calendar:
-- **Data intelligence** — Query, analyze, and export your Acuity Scheduling data
+
-- **Rapid operations** — Bulk actions that would take hours manually
+1. **Emergency rescheduling** — "Cancel all appointments for Dr. Smith tomorrow due to illness, send apology notes to clients, find next available slots for each"
-- **Cross-platform integration** — Combine Acuity Scheduling with other tools seamlessly
+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
+- Check availability → Book appointment → Send confirmation → Add to CRM → Set follow-up reminder
-- Search records → Update fields → Notify team
+- Query no-shows → Analyze patterns → Block problem times → Notify staff → Update booking rules
-- Analyze metrics → Create tasks → Schedule follow-ups
+- 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"*
+## 🎯 Example Prompts for Scheduling Managers
-- *"Create a new record with these details..."*
+
-- *"Export all data from last month"*
+Once connected to Claude, use natural language. Here are real scheduling workflows:
-- *"Update the status of X to Y"*
+
-- *"Generate a report of..."*
+### 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"
+### "Authentication failed" or "401 Unauthorized"
-- Verify your API credentials are correct
+- Verify both User ID and API Key are correct
-- Check that your API key hasn't been revoked
+- User ID should be numeric (e.g., 12345678, not "user123")
-- Ensure you have the necessary permissions
+- 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
+- Check that the path in `claude_desktop_config.json` is absolute (not relative)
-- Verify the build completed successfully (`dist/index.js` exists)
+- 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)
+- **[Acuity API v1 Docs](https://developers.acuityscheduling.com/reference/overview)** — Official API reference
-- [MCP Protocol Specification](https://modelcontextprotocol.io/)
+- **[Acuity Help Center](https://help.acuityscheduling.com/)** — Scheduling guides and tutorials
-- [Claude Desktop Documentation](https://claude.ai/desktop)
+- **[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`)
+2. Create a feature branch (`git checkout -b feature/calendar-sync`)
-3. Commit your changes (`git commit -m 'Add amazing tool'`)
+3. Commit your changes (`git commit -m 'Add Google Calendar sync tool'`)
-4. Push to the branch (`git push origin feature/amazing-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).

package.json

@@ -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",