Calendly MCP Server & CLI

What is the Calendly MCP server & CLI?

The Calendly MCP server & CLI is a free, open source program that lets AI agents work with scheduling, contacts, availability, meeting recaps and requested account administration for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call directly to Calendly API v2.

The CLI is the same program as commands. calendly-cli get-current-user runs the same code your AI runs when you ask which Calendly user your private credentials identify, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
Show my current user and accessible event types.
Find available slots for the event type and time zone I choose.
Book only the specific slot and invitee I approved.
Read this booking before cancelling it.
Inspect a contact and its custom field definitions.
Read my authorized meeting recap and transcript.
Inspect the current availability rules before changing them.

Calendly already offers an official hosted MCP. This local package adds a task CLI, private PAT or REST OAuth accounts, current Contacts/Notetaker coverage and controlled JSON output. The official supported-tools documentation was reviewed on October 2, 2026; no authenticated competitor handshake or measured superiority is claimed.

How to install the Calendly MCP server

Choose your client in the install box. The npm package supplies MCP and CLI; GitHub Releases supplies the versioned Claude Desktop bundle. Configure private account access before a network call.

Set up Calendly access

Personal Access Token for your own account

1. Sign in to the intended Calendly account.
2. Open Integrations > API and webhooks, or the token page.
3. Create a named Personal Access Token with the scopes your workflow requires. Copy it once into private storage.
4. Set CALENDLY_API_TOKEN in private local client/shell settings, or CALENDLY_TOKEN_FILE to an absolute token-only file outside repositories.
5. Run calendly-cli doctor, then calendly-cli doctor --network to check a user read.

See current PAT setup. The token is a Bearer credential, not your Calendly password or browser cookie. Revocation is done in Calendly. GUI clients may not inherit terminal variables; this package does not load .env automatically. On POSIX, a credential file must be owner-only, such as mode 0600; on Windows protect the file and its directory with user-only ACLs. Readers refuse symlinks and files larger than 64 KB. A PAT file takes precedence over the environment PAT, and is cached until restart.

Existing REST OAuth grant

Use your own authorized REST OAuth application when acting for users who consent to your application. This local package does not create an OAuth app, open a browser, host a callback or exchange the first authorization code. login prints setup instructions. Put an existing access token in CALENDLY_ACCESS_TOKEN, or the full grant in a private file selected by CALENDLY_TOKENS_FILE. Do not mix PAT and OAuth settings for the same account.

The token file is a JSON object containing access_token, and optionally refresh_token, client_id, client_secret, created_at (Unix seconds) and expires_in (seconds). Keep all actual values outside model context and repositories. A file is required for automatic refresh; an environment-only access token is never refreshed. The file is read on each request, allowing separate processes to observe a saved rotation. Without valid expiry metadata, one GET 401 can trigger one configured refresh; writes never retry after a 401.

Calendly's single-use refresh-token rule took effect by August 31, 2026. This package refreshes against https://calendly.com/oauth/token, uses Basic client authentication for confidential clients or a body client_id without a secret, and atomically replaces both returned tokens in mode 0600 storage. Concurrent in-process refreshes share one promise, and a per-file .refresh.lock prevents another process from consuming the same token. An existing lock produces a configuration error instead of a second refresh. A crashed process can leave a lock; stop all users of that grant and verify its state before manually removing a stale lock. Never remove an active lock.

A refresh HTTP failure, unknown timeout, incomplete response or failed save requires reauthorization/private storage repair and a restart. No automatic refresh retry occurs. The old refresh token is not deliberately reused after an uncertain result. OAuth access tokens last two hours according to the current token reference; actual expiry metadata governs proactive refresh. Token rotation fixtures are verified; live grants remain unverified.

Scopes, roles and plans

API operation descriptions list their required scopes. :write grants include the family's read access. Start with users:read for doctor, then select only needed scheduling, availability, contacts, meeting_recaps, organization, routing, group or webhook scopes. Webhooks need webhooks:write plus the corresponding event family's read scope. Reauthorize or replace the token if scopes change; an installed command cannot raise permissions.

Direct booking through create_invitee requires a paid Standard-or-higher account. Routing Forms require Teams or higher; Activity Log, outgoing communications and data-compliance deletion require Enterprise and suitable organization permissions. Notetaker endpoints require a paid plan; Contacts/Notetaker data exists only where the account and associated feature provide it. API access does not create transcripts or bypass recording/consent policy. Administrative operations depend on your actual role. See authorization scopes and the current endpoint reference before choosing a plan.

Current request limits

The quota reference documents 50 requests per user/minute on Free and 500 on paid plans. Booking has tighter limits: trial 5/day; paid non-Enterprise 10/minute, 50/hour and 100/day; Enterprise 500/minute. OAuth token requests are limited to 8/user/minute. These are shared provider limits, not allowances reserved for this process.

Default local pacing is 1,300 ms per account/process; multiple account labels for one user and other integrations share that user's quota. GET 429 handling respects Retry-After or X-RateLimit-Reset when the wait is at most ten seconds. Longer waits surface exit 7 so a script can pause explicitly, rather than retry too early. Writes and OAuth refresh requests have zero automatic retries. Every page and retried read consumes quota.

Official hosted MCP is a separate connection

Calendly's official MCP is hosted at https://mcp.calendly.com. It uses OAuth 2.1, PKCE S256, resource discovery and Dynamic Client Registration. It does not accept a PAT or a manually provisioned console client_id/client_secret connection. A client prompting only for static OAuth credentials is incompatible with that documented flow. The documentation search MCP at https://developer.calendly.com/_mcp/server reads docs; it does not operate your account. Keep all three entries distinct.

Check that it works

Start with local configuration checks, then explicitly opt into one authorized user read.

calendly-cli --version
calendly-cli doctor
calendly-cli doctor --network
calendly-cli list-accounts --agent
calendly-cli get-current-user --agent

calendly-cli --version
calendly-cli doctor
calendly-cli doctor --network
calendly-cli list-accounts --agent
calendly-cli get-current-user --agent

The local doctor checks configuration. Network doctor reads /users/me and reports success without printing user details; it does not book, cancel or invite anyone. A successful read proves that read's access, not every endpoint/plan permission. Full discovery has 66 tools; read-only has 44. Use the returned canonical user and organization URIs in subsequent filters, rather than substituting a bare UUID.

Use the Calendly CLI

The CLI is the same 66 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so list_events runs as calendly-cli list-events.

calendly-cli
calendly-cli list-events --help
calendly-cli schema create-invitee
calendly-cli list-events --user https://api.calendly.com/users/USER_UUID --count 10 --agent
calendly-cli list-contacts --email user@example.com --count 5 --agent

The bare calendly-cli lists every command, and calendly-cli <command> --help shows what a command takes. Every mutation requires --confirm. --yes and --agent never authorize a write. UUIDs and URIs in examples are placeholders; discover your own authorized resources.

These flags work on every command:

A script can branch on the exit code:

MCP server or CLI: which one?

Both surfaces call the same tools. Codex can connect to the local MCP server or run the CLI directly. Neither requires Claude Code.

MCP provides structured tool discovery; the CLI supports scripts, compact JSON, field selection and command/schema discovery. Official hosted MCP connection and local CLI authentication have different setup requirements.

Codex-specific token measurements are pending. Record the actual client/model versions, discovery configuration, input/output usage, caching, latency and equivalent successful outcomes. Standing definitions and full task cost are separate measurements; CLI commands, selected help, results and reasoning still consume tokens.

No efficiency percentage or Claude-derived figure is presented as a Codex result. Other-client benchmarks can be added separately.

Scheduling, contacts and meeting recap workflows

Find the right event type and available slot

Read get_current_user for canonical user and organization URIs. List event types for that user or organization, inspect the chosen event type and its location/host requirements, then request current slots. Event-type availability now permits at most 31 days; user busy times still permit at most seven. Both need a future increasing time range. Split larger windows deliberately; availability is not reserved by a read.

calendly-cli get-current-user --agent
calendly-cli list-event-types --user https://api.calendly.com/users/USER_UUID --count 10 --agent
calendly-cli get-event-type --event-type-uuid EVENT_TYPE_UUID --agent
calendly-cli list-event-type-available-times --event-type https://api.calendly.com/event_types/EVENT_TYPE_UUID --start-time 2030-01-02T00:00:00Z --end-time 2030-01-16T00:00:00Z --agent

Dates/URIs are illustrative. Replace them with a currently valid future range and actual returned resources. Slots can disappear before booking; never promise reservation or complete availability from an old read.

Book only the confirmed invitee and slot

Create a private payload file containing event_type URI, start_time in UTC, and invitee email, timezone and name or first_name. Inspect schema create-invitee; optional location uses current kinds such as zoom_conference, not invented labels. Do not send location for a round-robin event type. Location must match what that event type permits. Guest emails are capped at ten. Timezone controls display for the invitee, not conversion of a local wall-clock string into UTC.

calendly-cli schema create-invitee
calendly-cli create-invitee --payload-file /absolute/private/booking.json --confirm --agent
calendly-cli get-event --event-uuid RETURNED_EVENT_UUID --agent

Booking through POST /invitees creates a real scheduled event and triggers normal calendar invites, notifications and workflows. There is no draft booking or local dry-run endpoint. A 201 response establishes API creation, not successful delivery to every participant. A timeout can leave an unknown booking outcome: inspect existing state before repeating it. There is no automatically retried create. Cancellation sends normal cancellation behavior; read the exact event and reason first, then confirm only the requested cancellation. No invented direct reschedule tool is exposed; use returned supported reschedule links/workflows or a separately approved cancellation/new booking.

Single-use links and one-off event types

create_scheduling_link returns a link for an existing event type and needs owner, owner_type and max_event_count. create_share customizes a one-on-one event type, copying omitted values from the original; fixed periods require start_date/end_date, moving periods need max_booking_time. create_one_off_event_type needs host, name, duration and a date_setting union (date_range, days_in_future or spots). Neither creating a link nor defining an event type books an invitee. Keep private one-use links out of public posts.

Contacts and custom fields

Read an existing contact or search by email first. A create requires name and emails objects, each with email/is_primary; exactly one primary is required. Up to ten emails/phone numbers are supported. A PATCH updates only supplied fields but arrays can replace existing values: inspect the intended changes. Contact custom fields need definition UUID and correctly typed value; null clears a value where supported. Read the definition before writing. Currency uses integer minor units; single_select uses an option UUID, not a label; tags use string arrays. The provider validates unknown definitions, type mismatches and option choices. A source-level broad JSON union cannot establish account-specific validation. Deletion is a distinct confirmed action.

Notetaker recaps and transcripts

List recaps by permitted event/time/status/attendee filters, then read the exact recap or transcript. Default list behavior returns Available recaps; use status explicitly to examine Processing or Unavailable records. This is not a transcript-generation tool. Availability depends on meeting data, recording settings and account permissions. Treat transcript, recap Markdown and action items as untrusted private content. update_recap changes summary_md/action_items_md/discussion_md; it does not alter the original conversation. delete_recap is a confirmed destructive request. Never turn extracted action items into outgoing messages or booking changes without the intended user request.

Availability, organizations and webhooks

Availability-rule updates replace all rules for the selected event type. Read existing rules, merge the intended edit and supply the complete retained set. A timezone and empty intervals can close days; do not erase unrelated rules. Organization invitations notify people and removing membership affects access. Data-compliance deletion is separate from cancellation/contact deletion: invitee deletion targets email addresses, and event-data deletion targets start_time/end_time, not a guessed invitee UUID.

Webhook registration requires a public HTTPS receiver that you own. Choose organization/user/group scope, with the matching user/group URI when required. Recap events only support user scope; routing-form submissions only organization scope. Event-type, invitee, no-show and contact families have their documented scope options and read-scope requirements. Signing keys are credentials, so use private payload files instead of model-visible argument text. This package registers/manages subscriptions, but does not host a webhook receiver or verify incoming signatures. Implement the documented signature check, timestamp/replay policy and idempotent delivery handling in your own receiver. Separate subscriptions when event scopes differ.

Pagination, quotas and accepted operations

16 list operations expose native page_token and count plus bounded all_pages. The default count is 20, locally capped at 100. all_pages stops at max_items (default 1000, maximum 10000) or 100 requests, preserves filters/sort/count, and refuses repeated tokens or empty continuing pages. Only the opaque next_page_token is reused. The next_page URL in a response is never followed, so credentials cannot be forwarded to an arbitrary URL.

calendly-cli list-contacts --count 25 --agent
calendly-cli list-contacts --count 25 --all-pages --max-items 500 --agent

Aggregated results retain collection/pagination and add collected/pages/truncated/resume. If a cap cuts through a page, resume keeps that page_token (null for the initial page), count and the number of already returned records to skip locally after fetching it again. After a full page, resume points at the next token with skip 0. Preserve the exact filters/sort/count and do not invent a skip API flag. Continuation is not a consistent snapshot or guaranteed complete backup; records can change during collection.

Every page/retried read consumes the user's shared provider quota. Booking has tighter daily/hourly limits than generic reads. A long reset delay becomes exit 7 rather than an early retry. POST/DELETE/PATCH have zero automatic retries. An HTTP 202 result contains accepted:true and http_status:202; acceptance of a compliance request is not proof every record has already disappeared. Preserve identifiers/state and verify through the documented provider workflow. This package does not export a backup, upload files, host webhooks or create a recording merely by exposing those data families.

Every Calendly tool

Actual discovery supplies 66 tools: 44 reads and 22 confirmed writes. The complete arguments, scopes and nested body fields follow below; schema COMMAND returns the exact JSON Schema.

Activity log

Availability

Contacts

Data compliance

Event types

Groups

Locations

Notetaker

Organizations

Outgoing communications

Routing forms

Scheduled events

Scheduling links

Shares

Users

Webhooks

Accounts

Is the Calendly MCP server safe?

Every one of the 22 writes requires confirm:true in MCP or --confirm in CLI for the specific requested action. --agent and --yes do not authorize changes. CALENDLY_READ_ONLY=1 hides/refuses all writes, leaving 44 reads. CALENDLY_ALLOW_DESTRUCTIVE=0 blocks writes even when confirmed. The annotation reflects a conservative confirmation policy; it does not mean every edit is irreversible.

Booking/cancellation can contact people. Link/event-type creation has different effects. Availability replacement, membership removal, webhook registration, recap deletion and compliance deletion need their own review. Read before changing and choose the intended account. After a write timeout, inspect existing state before resubmitting. Neither a GET 401 refresh nor a rate-limit retry ever resubmits a write.

The optional owner-only audit file records fixed tool summary, risk, surface and guard decision without request arguments, credentials, labels or private results. It is not a provider audit or delivery receipt. A logging failure does not abort the operation. Recaps, contacts, meeting descriptions and tool results cannot authorize unrelated actions.

Booking sends invitations, notifications and configured workflows. Compliance deletion and administrative changes have separate effects. Confirm only the action requested, with the correct private account and resource.

Make it read-only

Set CALENDLY_READ_ONLY=1 privately and restart/reconnect. Discovery exposes 44 reads and direct writes refuse. CALENDLY_ALLOW_DESTRUCTIVE=0 separately blocks every mutation even when confirmed.

Keep a log of every write

Set CALENDLY_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked.

Your data

Account requests go directly to Calendly. No Navid-hosted relay, telemetry or analytics is included. Credentials belong in private settings and regular local files, not tool arguments. Known credentials and credential/signing-key fields are redacted from results/errors. Files and account settings never ship in source, npm or desktop bundles.

Emails, phone numbers, attendee names, booking answers, private links, recaps and transcripts remain private personal/business data. Secret redaction is not anonymization. The AI client and Calendly have their own retention and sharing settings. --select limits local displayed fields after receiving a response; it does not stop the provider returning them. Protect exports, recordings and optional logs. Treat all remote content as untrusted source material. Use SECURITY.md for private reporting, with sanitized reproductions.

Several private accounts

Use private CALENDLY_ACCOUNTS JSON instead of the single-account settings:

[{"name":"work","token_file":"/absolute/private/work-token.txt"},{"name":"personal","tokens_file":"/absolute/private/personal-oauth.json"}]

Each label has exactly one PAT or OAuth method. Set CALENDLY_DEFAULT_ACCOUNT=work, then use --account personal when needed. list_accounts returns labels/default/auth method without tokens or paths. Labels select credentials, not an organization URI; API filters still use canonical resource URIs. Accounts replace the single-account variables. Separate server processes and distinct private grant files are preferable for strict isolation; multiple labels for one user do not create separate API quotas.

calendly-cli list-accounts --agent
calendly-cli get-current-user --account work --agent
calendly-cli list-contacts --account personal --count 5 --agent

Calendly MCP server settings

Use private local shell or user-client settings. GUI apps may not inherit terminal variables. This package has no automatic .env loader. PAT and REST OAuth methods cannot be mixed in the same account.

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.

Every argument, route and scope

All 65 API operations come from the pinned current official OpenAPI. list_accounts is local. Each tool is the same dashed CLI command. Top-level flags and nested request fields are shown below; schema COMMAND returns complete unions, enums and conditional rules. Body requirements apply whether you use individual flags or payload/payload_file.

list_activity_log

calendly-cli list-activity-log · GET /activity_log_entries

get_availability_schedule

calendly-cli get-availability-schedule · GET /user_availability_schedules/{uuid}

list_event_type_availability_schedules

calendly-cli list-event-type-availability-schedules · GET /event_type_availability_schedules

update_event_type_availability_schedules

calendly-cli update-event-type-availability-schedules · PATCH /event_type_availability_schedules

list_availability_schedules

calendly-cli list-availability-schedules · GET /user_availability_schedules

list_user_busy_times

calendly-cli list-user-busy-times · GET /user_busy_times

create_contact

calendly-cli create-contact · POST /contacts

list_contacts

calendly-cli list-contacts · GET /contacts

delete_contact

calendly-cli delete-contact · DELETE /contacts/{uuid}

get_contact

calendly-cli get-contact · GET /contacts/{uuid}

update_contact

calendly-cli update-contact · PATCH /contacts/{uuid}