200 lines
4.5 KiB
Markdown
200 lines
4.5 KiB
Markdown
# Acuity Scheduling MCP Server
|
|
|
|
A comprehensive Model Context Protocol (MCP) server for Acuity Scheduling, providing full API integration with 59 tools and 12 interactive React applications.
|
|
|
|
## Features
|
|
|
|
### 🛠️ 59 MCP Tools
|
|
|
|
Complete CRUD operations across all Acuity Scheduling domains:
|
|
|
|
- **Appointments** (6 tools): List, get, create, update, cancel, reschedule
|
|
- **Calendars** (2 tools): List, get
|
|
- **Appointment Types** (5 tools): List, get, create, update, delete
|
|
- **Clients** (5 tools): List, get, create, update, delete
|
|
- **Availability** (2 tools): Get available dates and times
|
|
- **Blocks** (5 tools): List, get, create, update, delete (block out time)
|
|
- **Products** (5 tools): List, get, create, update, delete
|
|
- **Certificates** (4 tools): List, get, create, delete (gift certificates)
|
|
- **Coupons** (5 tools): List, get, create, update, delete
|
|
- **Forms** (5 tools): List, get, create, update, delete (intake forms)
|
|
- **Labels** (5 tools): List, get, create, update, delete
|
|
- **Packages** (5 tools): List, get, create, update, delete
|
|
- **Subscriptions** (5 tools): List, get, create, update, delete
|
|
|
|
### 🎨 12 React Applications
|
|
|
|
Modern, dark-themed UI applications:
|
|
|
|
1. **Appointment Calendar** - View and manage daily/weekly appointments
|
|
2. **Appointment Detail** - Detailed view of individual appointments
|
|
3. **Client Directory** - Browse and search all clients
|
|
4. **Client Detail** - Complete client profile with appointment history
|
|
5. **Availability Manager** - Manage available time slots and blocks
|
|
6. **Product Catalog** - View and manage products/services
|
|
7. **Certificate Viewer** - Manage gift certificates
|
|
8. **Coupon Manager** - Create and track discount coupons
|
|
9. **Form Builder** - Design and manage intake forms
|
|
10. **Analytics Dashboard** - Business insights and metrics
|
|
11. **Booking Flow** - End-to-end appointment booking experience
|
|
12. **Schedule Overview** - Weekly schedule summary and revenue tracking
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Set the following environment variables:
|
|
|
|
```bash
|
|
export ACUITY_USER_ID="your_acuity_user_id"
|
|
export ACUITY_API_KEY="your_acuity_api_key"
|
|
```
|
|
|
|
You can find your User ID and API Key in your Acuity Scheduling account under:
|
|
**Business Settings → Integrations → API**
|
|
|
|
## Usage
|
|
|
|
### As MCP Server
|
|
|
|
Build and start the server:
|
|
|
|
```bash
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
### With Claude Desktop
|
|
|
|
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"acuity": {
|
|
"command": "node",
|
|
"args": ["/path/to/acuity-scheduling-mcp-server/dist/main.js"],
|
|
"env": {
|
|
"ACUITY_USER_ID": "your_user_id",
|
|
"ACUITY_API_KEY": "your_api_key"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Development
|
|
|
|
Watch mode for TypeScript:
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
Type checking without building:
|
|
|
|
```bash
|
|
npm run typecheck
|
|
```
|
|
|
|
### Running React Apps
|
|
|
|
Each React app can be run independently using Vite:
|
|
|
|
```bash
|
|
cd src/ui/react-app/src/apps/appointment-calendar
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### API Client
|
|
|
|
The `AcuityClient` class (`src/clients/acuity.ts`) handles:
|
|
- Basic Authentication (userId + API key)
|
|
- Request/response handling
|
|
- Error handling
|
|
- Pagination support
|
|
|
|
### Tools
|
|
|
|
Each domain has its own tool file in `src/tools/`:
|
|
- Standardized input schemas
|
|
- Proper error handling
|
|
- Type-safe operations
|
|
|
|
### Type System
|
|
|
|
Complete TypeScript definitions in `src/types/index.ts` covering:
|
|
- Request/response types
|
|
- API entities
|
|
- Client configuration
|
|
|
|
## API Reference
|
|
|
|
### Example Tool Calls
|
|
|
|
**List appointments:**
|
|
```typescript
|
|
{
|
|
"name": "acuity_list_appointments",
|
|
"arguments": {
|
|
"minDate": "2024-01-01",
|
|
"maxDate": "2024-01-31",
|
|
"max": 100
|
|
}
|
|
}
|
|
```
|
|
|
|
**Create appointment:**
|
|
```typescript
|
|
{
|
|
"name": "acuity_create_appointment",
|
|
"arguments": {
|
|
"appointmentTypeID": 123,
|
|
"datetime": "2024-01-15T14:00:00",
|
|
"firstName": "John",
|
|
"lastName": "Doe",
|
|
"email": "john@example.com",
|
|
"phone": "555-1234"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Get availability:**
|
|
```typescript
|
|
{
|
|
"name": "acuity_get_availability_dates",
|
|
"arguments": {
|
|
"appointmentTypeID": 123,
|
|
"month": "2024-01",
|
|
"timezone": "America/New_York"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Tech Stack
|
|
|
|
- **Server**: TypeScript, Node.js, MCP SDK
|
|
- **UI**: React 18, TypeScript, Vite, Tailwind CSS
|
|
- **API**: Acuity Scheduling REST API v1
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Support
|
|
|
|
For issues or questions:
|
|
- Acuity API Docs: https://developers.acuityscheduling.com/
|
|
- MCP Docs: https://modelcontextprotocol.io/
|
|
|
|
---
|
|
|
|
Built with ❤️ for the Model Context Protocol
|