Cal.com MCP Server Cursor IDE Setup 2026: Hosted OAuth vs. Local API Key

How do you connect Cal.com to Cursor? There are two supported ways, and they're not interchangeable. Point Cursor's mcp.json at the hosted endpoint https://mcp.cal.com/mcp and let Cursor run through Cal.com's own OAuth 2.1 login — that's the fastest path and it never touches an API key. Or run @calcom/cal-mcp locally via npx, generate a CAL_API_KEY from your Cal.com account, and drop it into an env block. Both give Cursor's agent the same 30-plus tools for managing event types, bookings, schedules, and availability — the difference is entirely in how the connection authenticates.

Cal.com is the open-source scheduling tool a lot of dev teams already run instead of Calendly, so the MCP use case skews practical: an agent that can check your real availability, create an event type from a description, or reschedule a booking without you tabbing over to the dashboard.

Two Paths, Pick One

Most people should start with the hosted server. It's the option Cal.com's own docs lead with, and for good reason — there's no package version to keep updated, no key sitting in a config file, and the OAuth flow ties the connection to your actual Cal.com login the same way any browser-based sign-in would.

The local install exists for a narrower set of cases: CI/automation contexts where an interactive OAuth popup isn't an option, environments where you specifically want a scoped API key you can revoke independently of your login session, or you're running an older Cursor build that doesn't yet support OAuth-authenticated remote MCP entries in mcp.json. If none of those apply to you, skip to the hosted setup below and ignore the local instructions entirely.

What the Cal.com MCP Server Can Do

The tool surface is organized into seven categories, all mapping to the same Cal.com API v2 you'd otherwise call directly:

Two prompts that exercise this directly: "Create a 30-minute event type called 'Quick Chat'" and "Show me my available slots for next Monday." Both resolve to real API calls against your account, not a mock.

Prerequisites

Step 1: Hosted Setup (Recommended)

1. Open your Cursor mcp.json (Cursor Settings → Tools & MCP → Add Custom MCP, or edit ~/.cursor/mcp.json directly)
2. Add a calcom entry pointing at the hosted URL:

{
  "mcpServers": {
    "calcom": {
      "url": "https://mcp.cal.com/mcp"
    }
  }
}

3. Save, then click connect next to the calcom entry in Cursor's MCP settings panel
4. A browser window opens for Cal.com's OAuth 2.1 login — sign in and approve the connection
5. Cursor holds the resulting token; there's nothing further to configure

No CAL_API_KEY shows up anywhere in this path, which is the main appeal — nothing to rotate, nothing to accidentally commit.

Step 2: Local Install (API Key Path)

Skip this if you completed Step 1.

1. Generate an API key in Cal.com: Settings → Developer → API Keys → Create. Name it something you'll recognize later ("cursor-mcp-laptop" beats "key1") and copy the value immediately — Cal.com shows it once
2. Add a local calcom entry to mcp.json:

{
  "mcpServers": {
    "calcom": {
      "command": "npx",
      "args": ["@calcom/cal-mcp@latest"],
      "env": {
        "CAL_API_KEY": "cal_live_xxxx"
      }
    }
  }
}

3. Replace cal_live_xxxx with the key from step 1
4. Restart Cursor, or reload the MCP panel, so it picks up the new entry

Treat the key like any other production credential — it's scoped to your account, not to a single project, so a leaked key gives whoever has it the same booking/event-type access you have. Cal.com's own docs put it plainly: never share or commit the key, and if it's ever exposed, rotate it immediately from the same API Keys screen.

Verify the Connection

Ask Cursor something that requires a live round trip rather than something it could plausibly guess:

List my Cal.com event types and tell me which ones have a booking
in the next 3 days

If you get back real event type names and dates that match your actual account, the connection works. If Cursor says it has no calcom tools available, the entry either failed to load (check for a JSON syntax error in mcp.json — a missing comma after the env block is the most common one) or, on the hosted path, the OAuth handshake didn't complete.

Practical Workflows

Clearing a scheduling backlog without opening the dashboard

Show me all pending bookings that haven't been confirmed yet, and
confirm the ones with more than 2 attendees

Standing up a new event type mid-conversation

Create a 45-minute "Design Review" event type, limit it to weekday
afternoons, and use my default availability schedule

Checking availability before committing to a meeting time in chat

What's my earliest open 30-minute slot tomorrow, and does it
conflict with anything on my "Focus Time" schedule?

Where This Breaks Down

The hosted OAuth path assumes an interactive human at a browser. If you're wiring this into something headless — a script, a CI job, an agent running unattended overnight — OAuth's browser redirect has nothing to redirect to, and the local API-key path is the only one that works there.

The local path has its own failure mode worth knowing up front: @calcom/cal-mcp@latest means every restart can pull a newer version of the package. That's usually fine, but if Cal.com ships a breaking change to a tool's parameters, your Cursor agent's next call can fail with an error that has nothing to do with your config. Pin to a specific version (@calcom/cal-mcp@1.4.0 or whatever's current when you set this up) if you want setup to stay reproducible rather than always-latest.

Self-hosted Cal.com instances are a separate case entirely — the hosted mcp.cal.com endpoint talks to Cal.com's own cloud, not your self-hosted deployment. If you're running Cal.com yourself, the local install pointed at your instance's API base URL is the only path that reaches your data; check Cal.com's self-hosting docs for how to set a custom API base for the MCP package before assuming the hosted URL will work.

Troubleshooting

Connect button spins forever or the OAuth window never opens
Usually a popup blocker. Check your browser's blocked-popups indicator, allow it for Cursor, and click connect again.

"Unauthorized" errors after the local install worked yesterday
API keys can be revoked from the Cal.com dashboard without much warning if someone on your team is cleaning up old keys. Generate a fresh one and confirm it's the one actually referenced in mcp.json — a stale key from an old config left in env after a copy-paste is a close second cause.

Bookings tool works but event-type creation silently does nothing
Confirm the account connected (via OAuth login or the API key's owner) actually has permission to create event types — on team/org Cal.com plans, that can be restricted to admins even when booking-management is open to everyone.

mcp.json entry looks correct but Cursor shows zero Cal.com tools
Validate the JSON — a trailing comma or unmatched brace after adding the calcom block is the most common cause, and Cursor's error for this is often just "failed to load" without pointing at the line.

Local install: npx hangs on first run
The first invocation of npx @calcom/cal-mcp@latest downloads the package fresh; on a slow connection this can look stuck for 20-30 seconds before starting. Give it a minute before assuming it's broken.

Frequently Asked Questions

Q: Do I need a Cal.com API key to use the MCP server?
A: No, not if you use the hosted server at https://mcp.cal.com/mcp — that path authenticates through OAuth 2.1 in your browser. An API key is only needed for the local @calcom/cal-mcp install.

Q: Does the Cal.com MCP server work with self-hosted Cal.com instances?
A: The hosted mcp.cal.com endpoint connects to Cal.com's own cloud service, not a self-hosted deployment. Self-hosted users should use the local @calcom/cal-mcp package configured against their own instance's API.

Q: What can I do with the Cal.com MCP server besides booking meetings?
A: The tool set spans event types (create/update/delete/list), schedules and availability, conferencing app info, routing form calculations, and your own user profile — bookings are the largest category but not the only one.

Q: Is it safe to commit my CAL_API_KEY to a repo's mcp.json?
A: No. Treat it as a production secret — Cal.com's own guidance is to never share or commit it and to rotate immediately if it's exposed. Keep it in a local, untracked config or your OS keychain rather than a committed file.

Q: Why does the hosted server not need an API key at all?
A: It authenticates through your Cal.com login via OAuth 2.1 rather than a static token, so the "credential" is a session your browser establishes, not a string that lives in a config file and can leak.

Related Guides

Official docs cited