8e9d1ffb87
- Calendly API v2 client with auth, pagination, error handling - 27 MCP tools across 6 categories (events, event types, scheduling, users, orgs, webhooks) - 12 React MCP apps with dark theme and client-side state - Both stdio and HTTP modes supported - Full TypeScript types and documentation
182 lines
5.0 KiB
Markdown
182 lines
5.0 KiB
Markdown
# Calendly MCP Server
|
|
|
|
Complete Model Context Protocol (MCP) server for Calendly API v2 with 27 tools and 12 React UI apps.
|
|
|
|
## Features
|
|
|
|
### 🛠️ 27 MCP Tools
|
|
|
|
**Events (8 tools)**
|
|
- `calendly_list_scheduled_events` - List events with filters
|
|
- `calendly_get_event` - Get event details
|
|
- `calendly_cancel_event` - Cancel an event
|
|
- `calendly_list_event_invitees` - List invitees for an event
|
|
- `calendly_get_invitee` - Get invitee details
|
|
- `calendly_list_no_shows` - List no-shows
|
|
- `calendly_mark_no_show` - Mark invitee as no-show
|
|
- `calendly_unmark_no_show` - Remove no-show status
|
|
|
|
**Event Types (3 tools)**
|
|
- `calendly_list_event_types` - List event types
|
|
- `calendly_get_event_type` - Get event type details
|
|
- `calendly_list_available_times` - List available time slots
|
|
|
|
**Scheduling (3 tools)**
|
|
- `calendly_create_scheduling_link` - Create single-use scheduling link
|
|
- `calendly_list_routing_forms` - List routing forms
|
|
- `calendly_get_routing_form` - Get routing form details
|
|
|
|
**Users (3 tools)**
|
|
- `calendly_get_current_user` - Get current user info
|
|
- `calendly_get_user` - Get user by URI
|
|
- `calendly_list_user_busy_times` - List user busy times
|
|
|
|
**Organizations (6 tools)**
|
|
- `calendly_get_organization` - Get organization details
|
|
- `calendly_list_organization_members` - List members
|
|
- `calendly_list_organization_invitations` - List invitations
|
|
- `calendly_invite_user` - Invite user to organization
|
|
- `calendly_revoke_invitation` - Revoke invitation
|
|
- `calendly_remove_organization_member` - Remove member
|
|
|
|
**Webhooks (4 tools)**
|
|
- `calendly_list_webhook_subscriptions` - List webhooks
|
|
- `calendly_create_webhook_subscription` - Create webhook
|
|
- `calendly_get_webhook_subscription` - Get webhook details
|
|
- `calendly_delete_webhook_subscription` - Delete webhook
|
|
|
|
### 🎨 12 React MCP Apps
|
|
|
|
All apps feature dark theme and client-side state management:
|
|
|
|
1. **Event Dashboard** (`src/ui/react-app/event-dashboard`) - Overview of scheduled events
|
|
2. **Event Detail** (`src/ui/react-app/event-detail`) - Detailed event information
|
|
3. **Event Grid** (`src/ui/react-app/event-grid`) - Calendar grid view
|
|
4. **Event Type Manager** (`src/ui/react-app/event-type-manager`) - Manage event types
|
|
5. **Availability Calendar** (`src/ui/react-app/availability-calendar`) - View available times
|
|
6. **Invitee List** (`src/ui/react-app/invitee-list`) - Manage event invitees
|
|
7. **Scheduling Links** (`src/ui/react-app/scheduling-links`) - Create scheduling links
|
|
8. **Organization Members** (`src/ui/react-app/org-members`) - Manage team members
|
|
9. **Webhook Manager** (`src/ui/react-app/webhook-manager`) - Manage webhooks
|
|
10. **Booking Flow** (`src/ui/react-app/booking-flow`) - Multi-step booking interface
|
|
11. **No-Show Tracker** (`src/ui/react-app/no-show-tracker`) - Track no-shows
|
|
12. **Analytics Dashboard** (`src/ui/react-app/analytics-dashboard`) - Metrics and insights
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Set your Calendly API key as an environment variable:
|
|
|
|
```bash
|
|
export CALENDLY_API_KEY="your_api_key_here"
|
|
```
|
|
|
|
Get your API key from: https://calendly.com/integrations/api_webhooks
|
|
|
|
## Usage
|
|
|
|
### Stdio Mode (Default for MCP)
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
Use in your MCP client configuration:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"calendly": {
|
|
"command": "node",
|
|
"args": ["/path/to/calendly/dist/main.js"],
|
|
"env": {
|
|
"CALENDLY_API_KEY": "your_api_key"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### HTTP Mode
|
|
|
|
```bash
|
|
npm run start:http
|
|
```
|
|
|
|
Server runs on `http://localhost:3000`
|
|
|
|
Endpoints:
|
|
- `GET /health` - Health check
|
|
- `POST /` - MCP requests (tools/list, tools/call, resources/list, resources/read)
|
|
|
|
## API Client
|
|
|
|
The Calendly client (`src/clients/calendly.ts`) provides:
|
|
|
|
- ✅ Full Calendly API v2 support
|
|
- ✅ Bearer token authentication
|
|
- ✅ Automatic pagination handling
|
|
- ✅ Error handling with detailed messages
|
|
- ✅ Type-safe responses
|
|
|
|
## Architecture
|
|
|
|
```
|
|
src/
|
|
├── clients/
|
|
│ └── calendly.ts # Calendly API v2 client
|
|
├── tools/
|
|
│ ├── events-tools.ts # Event management tools
|
|
│ ├── event-types-tools.ts # Event type tools
|
|
│ ├── scheduling-tools.ts # Scheduling & routing tools
|
|
│ ├── users-tools.ts # User management tools
|
|
│ ├── organizations-tools.ts # Organization tools
|
|
│ └── webhooks-tools.ts # Webhook tools
|
|
├── types/
|
|
│ └── index.ts # TypeScript definitions
|
|
├── ui/
|
|
│ └── react-app/ # 12 React MCP apps
|
|
├── server.ts # MCP server setup
|
|
└── main.ts # Entry point (stdio + HTTP)
|
|
```
|
|
|
|
## Development
|
|
|
|
### Build
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
### Watch Mode
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
### Run React Apps
|
|
|
|
Each app is standalone:
|
|
|
|
```bash
|
|
cd src/ui/react-app/event-dashboard
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
## Resources
|
|
|
|
- Calendly API Documentation: https://developer.calendly.com/api-docs
|
|
- Model Context Protocol: https://modelcontextprotocol.io
|
|
- MCP SDK: https://github.com/modelcontextprotocol/typescript-sdk
|
|
|
|
## License
|
|
|
|
MIT
|