Integrations

Connect Calendr MCP

13 Aug 2026 · by Peter Grillet

The Calendr MCP server connects calendr.so to AI assistants such as Cursor and Claude Desktop. Once configured, your assistant can call Calendr tools to check availability, create bookings, manage contacts and organisations, read form submissions, invite team members, and pull booking reports — all scoped to your firm.

This guide walks through generating an API token and adding the MCP server to your AI client.

What you need before you start

  • A calendr.so account with access to your firm
  • Node.js 18 or later installed (the MCP server runs via npx)
  • An MCP-compatible client such as Cursor or Claude Desktop
  • Permission to generate API tokens (available from Settings → Integrations)
Note on permissions: API tokens inherit the permissions of the user who created them. Standard users can book meetings and manage contacts. Admin-only actions — such as inviting users, archiving colleagues, and deleting contacts or organisations — require a token created by a firm admin.

Step 1: Generate an API token

  1. In Calendr, go to Settings → Integrations
  2. Under API tokens, enter a name that helps you remember where the token is used (for example, Cursor on MacBook or Claude Desktop)
  3. Click Generate API token
  4. On the token page, copy the token immediately — it is shown while your session is active, but will not be displayed again after you sign out
Each token is firm-scoped. Any MCP tool call made with that token only accesses data for your firm.

Step 2: Copy the MCP configuration

On the same token page, scroll to MCP configuration. Calendr shows a ready-to-paste JSON block for your AI client.

It looks like this:

{
  "mcpServers": {
    "calendr": {
      "command": "npx",
      "args": ["-y", "@calendr/mcp"],
      "env": {
        "CALENDR_API_TOKEN": "your-token-here",
        "CALENDR_API_BASE": "https://calendr.so"
      }
    }
  }
}

Replace your-token-here with the API token you copied in Step 1 if it is not already filled in.

CALENDR_API_BASE should be:
  • https://calendr.so

Step 3: Add the server to Cursor

  1. Open Cursor Settings
  2. Go to MCP (or Features → MCP depending on your Cursor version)
  3. Click Add new MCP server or edit your MCP config file
  4. Paste the Calendr server block from Step 2
If you edit a config file directly, the mcpServers object from Step 2 can be merged into your existing MCP configuration. Keep any other servers you already use — only add the calendr entry.

Save the configuration and restart Cursor if prompted
You should see calendr listed as a connected MCP server with the available tools loaded.

Step 4: Add the server to Claude Desktop

  1. Open Claude Desktop’s MCP config file:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  2. Add the calendr server block from Step 2 inside the top-level mcpServers object
  3. Save the file and restart Claude Desktop

If the file is empty or new, wrap the server block like this:

{
  "mcpServers": {
    "calendr": {
      "command": "npx",
      "args": ["-y", "@calendr/mcp"],
      "env": {
        "CALENDR_API_TOKEN": "your-token-here",
        "CALENDR_API_BASE": "https://calendr.so"
      }
    }
  }
}

Step 5: Test that it works

Ask your assistant a simple, read-only question first. For example:
  • “List my Calendr event types”
  • “How many bookings did we have in the last 30 days?”
  • “Search for organisations named Acme”
If the MCP server is connected correctly, the assistant will call Calendr tools and return JSON results from your firm.

Then try a low-risk write action:
  • “Check availability for [event type] tomorrow”
  • “Create a booking for [name] at [time] on [event type]”
Confirm the booking appears in Calendr before relying on the integration for client-facing work.

What the MCP server can do

Scheduling

  • list_event_types — List booking pages for your firm
  • get_availability — Get open slots for an event type on a date
  • create_booking — Book a meeting
  • get_booking — Fetch booking details
  • cancel_booking — Cancel a booking (requires confirm=true)
  • reschedule_booking — Move a booking to a new time

CRM

Calendr stores client records across three related types:
  • Organisation — the company or client entity
  • Person — an individual’s name
  • Contact card — links a person to an email address and optionally an organisation
Available tools:
  • list_organizations, get_organization, create_organization, update_organization, delete_organization
  • list_people, get_person, create_person, update_person, delete_person
  • list_contact_cards, update_contact_card, delete_contact_card
If an organisation name changes in an external CRM, you would typically use update_organization. To change a person’s email or link them to a different organisation, use update_contact_card.

Form submissions (read-only)

  • list_qualifying_form_submissions
  • list_booking_form_submissions

Team management

  • list_team_members — List users in the firm
  • invite_user — Invite a new colleague (admin only)
  • archive_user — Archive a user (admin only; requires confirm=true)

Reporting

  • get_booking_summary — Booked, cancelled, and rescheduled counts for a date range
  • get_booking_breakdown — Breakdown by team member or event type

Permissions and security

Tokens inherit your account role. If you create a token as a standard user, admin-only tools will not work. Create separate tokens for different people or devices so you can revoke one without affecting others.
Destructive actions require confirmation. Cancelling bookings, deleting contacts, deleting organisations, and archiving users require confirm=true in the tool call. Your assistant should ask before performing these actions.
Rate limits apply:
  • 120 requests per minute per token
  • 20 destructive actions per 5 minutes per token
  • 10 invitations per hour per token
Revoke tokens you no longer use. Go to Settings → Integrations, find the token, and click Revoke. Any MCP client using that token will stop working immediately.
Write actions are recorded in Calendr’s API audit log with the token, user, and action details.

Troubleshooting

MCP server does not appear in Cursor or Claude
  • Confirm Node.js 18+ is installed (node --version)
  • Confirm the JSON config is valid (no trailing commas, matching braces)
  • Restart the AI client after saving the config
Authentication errors / 401
  • Check the token is copied correctly with no extra spaces
  • Confirm the token has not been revoked
  • Generate a new token if needed
403 Forbidden
  • The action requires admin permissions — create the token from an admin account, or ask a firm admin to perform the action
422 Validation failed or confirmation required
  • Destructive actions need confirm=true
  • Check required fields are provided (for example, invitee email on bookings)
Tools work locally but not in production
  • Confirm CALENDR_API_BASE is set to https://calendr.so in production configs
Token no longer visible
  • Token secrets are only shown during your active session on the token page
  • If you did not save it, revoke the token and generate a new one

Quick setup checklist

  • Node.js 18+ installed
  • API token generated in Settings → Integrations
  • Token copied and saved securely
  • MCP config added to Cursor or Claude Desktop
  • AI client restarted
  • Test query returned event types or booking data
  • Token revoked for any device or person that no longer needs access
#MCP #API #Cursor #Claude Desktop #Integrations

Related help articles

Connect Karbon to Calendr (Complete Guide)

Calendr’s Karbon integration links your booking pages to your Karbon practice management workspace. This guide walks through connecting the integration and configuring your event types.