carly-cli
OfficialThis MCP server provides an agent-native interface to Carly, an AI scheduling assistant, for managing calendars, booking pages, event types, slots, and bookings.
Authentication & Profile
whoami— Verify identity and confirm the current user/API key
Calendars
calendars_list— List connected calendars (Google, Outlook, etc.) with conflict-checking statuscalendars_select/calendars_unselect— Toggle whether a calendar counts against booking-page availability (requiresbooking_pages:write)
Booking Pages
booking_pages_list— List all booking pagesbooking_pages_get— Retrieve a specific booking page by event type IDbooking_pages_create— Create a new booking page (title, slug, duration, location, video provider, timezone, availability windows, custom questions, buffers, etc.)booking_pages_update— Update any subset of fields on an existing booking page (nested fields replace wholesale)booking_pages_delete— Soft-deactivate a booking page (reversible via update)
Event Types
event_types_list— List your own event types, or a public profile's active event types by username
Slots
slots_list— List available booking slots within a time range, identified by event type ID or username + slug
Bookings
bookings_list— List bookings with optional filters (status, event type, time range, limit)bookings_get— Retrieve a single booking by its UID
Note: Booking write operations (create, cancel, reschedule) are intentionally not exposed — use the Carly web dashboard for those.
Allows connecting and managing Google Calendar accounts for scheduling, including OAuth-based authentication and calendar listing.
Supports connecting Zoom for video conferencing as a meeting provider in scheduling workflows.
carly-cli
Carly Forms & Bookings is the existing Carly CLI, expanded to manage forms alongside booking pages. The carly command, npm package carly-ai, saved credentials and existing MCP tool names stay compatible.
One command registry drives both the shell and carly mcp. It covers booking pages and their settings, working-hours schedules, private links, reminders, branding, team routing attributes, booking workflow connections, Calendly imports, forms and form submissions. Calendar, identity, slot and booking reads remain available for these workflows.
This is the local stdio MCP version of the CLI. The general Carly and Carly Teams hosted MCPs are separate products with their own setup; this package does not proxy those tools.
Version 0.4 adds form and booking-control commands that require the corresponding /api/v1/forms and booking-control API routes on your Carly server. Updating this package does not deploy that backend. Older servers continue to support the existing commands and may return 404 for the new ones.
Install
npm install -g carly-aiOr run from source:
git clone https://github.com/usecarly/carly-cli.git
cd carly-cli
npm install && npm run build
npm link # exposes `carly` on PATHRelated MCP server: booking_chest
Quick start
Brand new user? Sign up from the CLI — it opens the OAuth consent page in your browser, connects your calendar, and you land back in the dashboard. Then mint an API key and run carly login.
carly signup # opens Google OAuth (use --with microsoft for Outlook)
# ... approve in browser, then:
carly login # paste a personal API key from /integrations (enable forms scopes for forms)Already have a Carly account?
# 1. Authenticate (interactive — saves to ~/.carly-cli/config.json)
carly login
# 2. Confirm the key works
carly profile whoami --pretty
# 3. See what you have
carly calendars list --output table
carly booking-pages list --output table
carly schedules list --output table
carly bookings list --output table
carly forms list --output tableConnect additional calendars / video providers
carly calendars connect google # Google Calendar (also handles first-time signup)
carly calendars connect microsoft # Outlook calendar + Teams meetings
carly calendars connect zoom # Zoom (for video-only; requires existing Carly account)Each command opens the dashboard's OAuth page in your browser. No tokens touch the CLI.
Authentication
Resolved in priority order:
# | Method | Example |
1 |
|
|
2 |
|
|
3 | Config file |
|
Base URL defaults to https://carlyassistant.com and can be overridden with --api-base-url or CARLY_API_BASE_URL. The legacy dashboard.carlyassistant.com host serves the same API and still works.
Mint a personal key at <base-url>/integrations#api-key-create-form and select the scopes you need. Forms require forms:read and/or forms:write; these scopes are off by default. Booking keys can also be created on the booking-pages screen. Team credentials stay within their team and cannot access personal forms. Scopes and live resource permissions are enforced server-side; see Scopes below.
MCP server setup
carly mcp starts an MCP server over stdio that exposes every API command in the shared registry as a tool to any MCP-compatible client.
Claude Code
claude mcp add carly -- carly mcp
# or, before `npm link`:
claude mcp add carly -- node /path/to/carly-cli/dist/mcp.jsClaude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"carly-forms-bookings": {
"command": "carly",
"args": ["mcp"],
"env": {
"CARLY_API_KEY": "carly_live_xxxx"
}
}
}
}Cursor
Add to .cursor/mcp.json:
{
"mcpServers": {
"carly-forms-bookings": {
"command": "carly",
"args": ["mcp"],
"env": {
"CARLY_API_KEY": "carly_live_xxxx"
}
}
}
}Command reference
Auth + utility
carly login # Interactive API key setup
carly logout # Remove stored credentials
carly auth-status # Show current auth resolution
carly mcp # Start MCP server (stdio)
carly profile whoami # Confirm identity + key validityCalendars
carly calendars list # Connected calendars (provider + account + key)Use calendar_key values from this list as the --calendar-key argument when creating/updating booking pages.
Booking pages
carly booking-pages list
carly booking-pages get <event-type-id>
carly booking-pages create --title <title> [options]
--slug <slug> # URL slug (e.g. "15min")
--description <text>
--duration <min> # Meeting length (default 30)
--location <loc> # Physical location or URL
--video-provider <name> # google_meet, teams, zoom, ...
--calendar-key <key> # From `carly calendars list`
--timezone <tz> # IANA TZ (e.g. America/New_York)
--username <username> # Profile username (lowercase)
--display-name <name>
--event-name-template <tpl>
--min-notice-minutes <n> # Default 120
--max-days-ahead <n> # Default 60
--before-event-buffer <min>
--after-event-buffer <min>
--slot-interval <min>
--availability <json> # [{"days":[1,2,3,4,5],"start_time":"09:00","end_time":"17:00"}]
--date-overrides <json> # [{"date":"2026-12-24","windows":[]}] (empty windows = day blocked)
--custom-questions <json> # [{"label":"Company","type":"text","required":true}]
--duration-options <list> # CSV (15,30,60) or JSON array ([15,30,60])
--widgets <json> # Page content blocks
--schedule-id <id> # Book on a library schedule (see `carly schedules list`); omit to follow your default
--schedule-name <name> # Name for the schedule created from --availability/--timezone
# Team pages
--organization-id <id> --scheduling-type <round_robin|collective|managed>
--hosts <json> # [{"user_id":12,"is_fixed":false,"priority":1,"schedule_id":null}]
--assign-all-team-members <true|false> --member-fields-unlocked <true|false>
--rr-reset-interval <day|month> --rr-timestamp-basis <created_at|start_time>
--include-no-show-in-rr-calculation <true|false> --reschedule-with-same-round-robin-host <true|false>
# Limits and windows
--booking-window-mode <rolling|business_days|range> --booking-window-business-days <n>
--booking-window-start <date> --booking-window-end <date>
--booking-limit-count <n> --booking-limit-period <day|week|month|year> --booking-limit-duration-minutes <n>
--booker-active-booking-limit <n> --offset-start-minutes <n> --only-show-first-available-slot <true|false>
# Guest controls and privacy
--requires-confirmation <true|false> --confirmation-threshold-minutes <n>
--disable-guests / --disable-cancelling / --disable-rescheduling <true|false> --minimum-reschedule-notice <n>
--hide-calendar-notes / --hide-calendar-event-details / --hide-organizer-email <true|false>
--requires-private-link <true|false> --locked-timezone <tz> --color <#RRGGBB>
--success-redirect-url <url> --forward-params-success-redirect <true|false>
# Seats, recurrence, reminders
--seats-per-time-slot <n> --seats-show-attendees <true|false> --seats-show-availability-count <true|false>
--recurrence-frequency <weekly|monthly|yearly> --recurrence-interval <n> --recurrence-occurrences <n>
--reminder-configs <json>
carly booking-pages update <event-type-id> [options] # Same flags as create, all optional
--is-active <true|false> # Enable or disable the page
carly booking-pages delete <event-type-id> # Soft-delete: sets is_active=false. Re-activate with `update <id> --is-active true`.
carly booking-pages check-username <username> # Is this profile username free?Nested-field notes:
--availabilitydays are numbered Sunday=0, Monday=1, …, Saturday=6. Times are HH:MM in the page's timezone.--date-overridesare one-off exceptions that replace the weekly hours for a single date, read in the page's timezone."windows": []blocks the date entirely; otherwise only the listed windows are bookable. An override can also open a date the weekly pattern leaves closed. Max 100 overrides / 500 windows per page.--availabilityand--date-overridesare independent — updating one leaves the other intact. Pass--date-overrides '[]'to clear every override without touching the weekly hours.--custom-questionstypeis one oftext,textarea,number,phone,email,select,checkbox,radio,boolean.optionsis only required forselect/radio.On
update, any nested field you pass replaces the previous value wholesale — there is no partial merge.MCP callers may pass these as native arrays/objects instead of stringified JSON.
Schedules (6 commands)
Working hours live in a library of schedules, not on the page. You have one default (every page without --schedule-id follows it); a team can own shared schedules a team page imposes on every host. booking-pages update --availability edits the page's own schedule — or, for a page that follows your default, gives it a copy of its own.
carly schedules list --output table
carly schedules get <schedule-id> # hours, overrides, timezone, and the pages using it
carly schedules create --name "Working hours" --timezone America/New_York --availability '<json>'
carly schedules create --name "Front desk" --organization-id 4 --timezone America/Chicago --availability '<json>'
carly schedules create --for-user-id 388 # seed a 9-5 default for a team member with no hours
carly schedules update <schedule-id> --timezone Europe/Berlin --availability '<json>' --date-overrides '<json>'
carly schedules duplicate <schedule-id> --data '{"name":"Summer hours"}'
carly schedules set-default <schedule-id>
carly schedules delete <schedule-id> # refused while a page uses itEvent types
carly event-types list # Caller's own event types
carly event-types list --username <username> # Public active event types for a profileSlots
carly slots list --event-type-id <id> --start-time <iso> --end-time <iso> [--duration <min>]
# or, public access via profile+slug:
carly slots list --username <username> --event-type-slug <slug> \
--start-time <iso> --end-time <iso>Bookings
carly bookings list [options]
--status <status> # accepted, cancelled, rescheduled, ...
--event-type-id <id>
--limit <n> # 1–1000, default 100
--start-time <iso>
--end-time <iso>
carly bookings get <uid>bookings:write (create, cancel, reschedule) is intentionally not exposed on this CLI or the MCP surface; use the web dashboard.
Forms
carly forms list
carly forms get 42
carly forms create --name "Watch the video" \
--form-fields '[{"key":"email","label":"Email","type":"email","required":true}]' \
--routes '{"rules":[],"fallback":{"type":"redirect","url":"https://example.com/watch"}}'
carly forms update 42 --form-fields @fields.json --notify-email false
carly forms update 42 --routes null # clear routing
carly forms update 42 --status paused
carly forms submissions 42 --limit 50 --offset 0
carly forms routing-targets
carly forms crm-fields
carly forms phone-regions
carly forms test-routing --form-fields @fields.json --routes @routes.json --answers '{"email":"guest@example.com"}'
carly forms upload-logo --content-base64 @logo.png --mime-type image/png
carly forms delete 42--form-fields edits the form; --fields retains its existing output-filtering meaning. Create and update also support --intro-text, --submit-label, --success-message, --legal, --appearance, --webhook-url and --status. Nested JSON accepts inline JSON or @file; MCP clients can supply native objects and arrays. Save the logo upload's logo_key in appearance.logo_key. Send an empty webhook URL to remove a webhook. Only supplied settings change, and explicit null clears routing, legal or appearance. Keep existing field keys when editing labels so routing and workflows retain their references.
Removing workflow-bound fields requires forms update --force. Deleting a form with dependent workflows requires forms delete --force, which pauses those workflows and permanently deletes the form and its submissions.
Booking controls
These commands use the same validation and permissions as the booking editor. --data accepts the documented JSON body or @file. Run each command with --help for its body shape.
carly private-links list 7
carly private-links create 7 --data '{"max_usage_count":1}'
carly private-links revoke 7 12
carly booking-reminders preview 7 --data @reminder.json
carly booking-reminders test 7 --data @reminder.json
carly booking-reminders insights 7
carly booking-connections list 7
carly booking-connections setup 7 --template-id TEMPLATE_ID
carly booking-connections create 7 --data @connection.json
carly booking-branding get
carly booking-branding update --data '{"display_name":"My business"}'
carly booking-branding upload-logo --content-base64 @logo.png --mime-type image/png
carly booking-branding delete-logo
carly booking-branding set-removal 2 --data '{"hide_carly_branding":true}'
carly booking-attributes list 2
carly booking-attributes create 2 --data @attribute.json
carly booking-attributes update 2 4 --data '{"enabled":false}'
carly booking-attributes assign 2 3 4 --data '{"values":["East"],"weight":100}'
carly booking-attributes delete 2 4
carly booking-import preview --data @calendly-token.json
carly booking-import calendly --data @calendly-import.jsonBranding commands accept --org <id> for an authorized team. Attribute assignment arguments are organization ID, membership ID, then attribute ID; use option IDs for select attributes and scalar values for text/number attributes. Reminder tests send to your own email and retain the server's rate limits. Private-link URLs grant booking access; keep them private.
Booking page create/update already include redirect URLs, forwarded query parameters, recurring meetings, team hosts, routing rules, custom questions, reminders, availability, limits and content blocks. Use --help for the complete options. For example:
carly booking-pages update 7 --success-redirect-url https://example.com/watch
carly booking-pages update 7 --success-redirect-url null
carly booking-pages update 7 --recurrence-frequency nullOutput formats
Every data-returning command accepts these global/per-command flags:
Flag | Behavior |
| Single-line JSON to stdout |
| Pretty-printed JSON |
| Shortcut for |
| Fixed-width table; columns come from the command's |
| Narrow JSON keys; override table columns |
| Suppress stdout (exit code only) |
Table mode flattens Carly's {items: [...]} envelope and the {slots: {date: [...]}} map automatically. For single-object responses (e.g. bookings get), table mode falls back to pretty JSON with a note on stderr.
# Default compact JSON
carly bookings list
# Human-friendly table
carly bookings list --output table
# Just the columns you care about
carly bookings list --output table --fields uid,status,start_time
# Pretty JSON with a field filter
carly bookings list --fields uid,status,start_time --prettyScopes
Scope | Needed for |
|
|
| Booking page writes, schedule writes, private-link writes, reminder tests, branding, attributes and imports |
| Form list/get, submissions, routing targets, CRM fields, phone regions and routing tests |
| Form create/update/delete and logo upload |
| Creating a booking workflow connection |
|
|
bookings:write is not accepted when minting new keys and is not surfaced on this CLI or the MCP server. Existing keys that were minted with it still authenticate, but no write paths are wired up for bookings.
Architecture
src/
├── index.ts # CLI entry (Commander.js)
├── mcp.ts # MCP entry (re-exports server.ts)
├── core/
│ ├── types.ts # CommandDefinition — single source of truth
│ ├── client.ts # CarlyClient (fetch + retry/backoff)
│ ├── auth.ts # Flag → env → config resolution
│ ├── config.ts # ~/.carly-cli/config.json (mode 0600)
│ ├── handler.ts # executeCommand (path/query/body routing)
│ ├── output.ts # json | pretty | table renderer + --fields
│ └── errors.ts # AuthError, NotFoundError, RateLimitError, ...
├── commands/
│ ├── index.ts # allCommands registry + Commander wiring
│ ├── auth/ # login, logout, auth-status
│ ├── profile/ # whoami
│ ├── calendars/ # list
│ ├── booking-pages/ # list, get, create, update, delete
│ ├── forms/ # forms, routing, submissions, logos
│ ├── booking-controls/ # private links, reminders, branding, attributes, imports
│ ├── schedules/ # working hours and date overrides
│ ├── event-types/ # list
│ ├── slots/ # list
│ └── bookings/ # list, get
└── mcp/
└── server.ts # Register every CommandDefinition as an MCP toolEach CommandDefinition carries:
name — MCP tool name (e.g.
booking_pages_update)group / subcommand — CLI routing (e.g.
carly booking-pages update)inputSchema — Zod schema shared by CLI validation and MCP input schema
endpoint — HTTP method + path template (e.g.
PATCH /booking-pages/{eventTypeId})fieldMappings — per-field routing to
path,query, orbodydefaultColumns — optional; columns used by
--output tablehandler — executes via
CarlyClient
Development
git clone https://github.com/usecarly/carly-cli.git
cd carly-cli
npm install
# Hot reload via tsx (no build step)
npm run dev -- profile whoami --pretty
npm run dev -- bookings list --output table
# Validation
npm run typecheck
npm test
npm run fields:check
# Production build
npm run build # → dist/index.js + dist/mcp.js
npm link # expose `carly` on PATHTo add a command:
Author a
CommandDefinitioninsrc/commands/<group>/index.tsExport it from the group's
*CommandsarrayInclude the group in
src/commands/index.ts→allCommandsnpm run build && carly <group> <subcommand> --help
Both the CLI and the MCP server pick it up automatically. The field check covers booking-page, schedule and form create/update inputs. It uses a sibling backend checkout when present, otherwise the public snapshot in schemas/api_v1_fields.txt; set CARLY_API_FIELDS_FILE to override it. Refresh that snapshot alongside server schema changes.
Read requests retry transient failures. Writes are never automatically retried because creating a form, sending a test reminder or importing pages may already have taken effect.
License
MIT
Available Tools
13 toolsbooking_pages_createC
Create a new booking page. Requires the booking_pages:write scope. Accepts nested fields (--availability, --custom-questions, --duration-options) as JSON.
Inputs: title (required), slug, description, duration, +15 more.
booking_pages_deleteA
Deactivate (pause) a booking page by its event type ID. The server soft-deletes: the page is hidden from public booking (is_active=false) but the row is retained and the page can be re-activated via update <id> --is-active true. Requires the booking_pages:write scope.
Inputs: eventTypeId (required).
booking_pages_getA
Get a single booking page by its event type ID
Inputs: eventTypeId (required).
booking_pages_listA
List the authenticated user's booking pages (event types with public links)
Inputs: no named parameters.
booking_pages_updateA
Update an existing booking page by its event type ID. Requires the booking_pages:write scope. Only fields you pass are updated. Nested fields (--availability, --custom-questions, --duration-options) accept JSON and replace the previous value.
Inputs: eventTypeId (required), title, isActive, slug, +17 more.
bookings_getA
Get a single booking by its UID
Inputs: uid (required).
bookings_listB
List the authenticated user's bookings. Supports filters for status, event type, and time range.
Inputs: status, eventTypeId, limit, startTime, +1 more.
calendars_listA
List connected calendars for the authenticated user. The selected field mirrors the "Check for conflicts on" state in the web UI — calendars with selected: true count against booking-page availability.
Inputs: no named parameters.
calendars_selectA
Mark a calendar as counting against booking-page availability ("Check for conflicts on"). Requires the booking_pages:write scope. The flag is account-wide — every booking page on this calendar's integration will honor it on the next availability check.
Inputs: calendar_key (required).
calendars_unselectA
Stop counting a calendar against booking-page availability. Requires the booking_pages:write scope. Inverse of carly calendars select.
Inputs: calendar_key (required).
event_types_listA
List event types. Without --username, returns the authenticated caller's own event types. With --username, returns that public profile's active event types.
Inputs: username.
slots_listB
List available booking slots in a time range. Provide either --event-type-id, or both --username and --event-type-slug.
Inputs: startTime (required), endTime (required), eventTypeId, username, +2 more.
whoamiA
Show the user the API key belongs to
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool targets a distinct resource and action: booking pages have separate CRUD tools, bookings have get/list, calendars have list/select/unselect, plus event_types_list, slots_list, and whoami. No two tools overlap in purpose.
All tool names follow a consistent pattern of `resource_action` in lowercase with underscores (e.g., booking_pages_create, calendars_select). No mixing of conventions or verb styles.
13 tools is well-scoped for a booking management CLI. It covers all necessary operations without being too few or excessive, providing a focused and manageable surface.
The tool set provides full CRUD for booking pages, listing bookings, calendar management, event types, slots, and user info. No obvious gaps for the intended domain of managing bookings and availability.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Hosted Google Calendar MCP server for AI agents. No self-hosting or Google Cloud setup.
MCP server exposing the Backtest360 engine API as tools for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server that connects AI agents to calendars, bookings, and scheduling polls via the Model Context Protocol.2210 npmMIT
- FlicenseBqualityDmaintenanceMCP server for Cal.com scheduling, providing ~70 tools to manage schedules, event types, bookings, calendars, webhooks, and teams. Enables natural language control of Cal.com from Claude or any MCP-compatible client.68-
- AlicenseAqualityDmaintenanceMCP server for the Cal.com API v2, providing 24 tools for managing bookings, event types, availability slots, schedules, calendars, user profile, and out-of-office entries.246 npm1MIT
- AlicenseNot gradedqualityDmaintenanceExposes Cal.com scheduling tools to AI agents via MCP, enabling listing event types, checking availability, and managing bookings (create, cancel, reschedule).67 npmMIT