<- CalendarMCP

API reference

Calendar MCP documentation

Complete reference for all CalendarMCP tools. Connect through the Model Context Protocol.

Quick start

1. Connect Google Calendar with OAuth, or use service-account sharing for Google Advanced Protection.

2. Copy your API key from the dashboard.

3. Tighten calendar access in the Read / Write matrix.

Endpoint
https://calendarmcp.ai/api/mcp
Auth header
Authorization: Bearer YOUR_API_KEY
Machine-readable JSON
GET /api/docs

Multi-account and permissions

A single CalendarMCP API key can hold multiple Google accounts. Each calendar has its own Read / Write grant for the key.

OAuth

Sign in with Google. Full read and write, including attendee invites.

Service account

Share a calendar with CalendarMCP. Works when Advanced Protection blocks OAuth.

Known limits

  • Service-account calendars cannot invite or change attendees on personal calendars.
  • create_calendar requires OAuth. Service-account users must create/share new calendars manually.
  • Google Advanced Protection users must use the service-account sharing flow.
  • Text search may not work on non-primary calendars.
  • batch_update_events accepts 50 events per call.

Tools reference

11 calendar tools

View JSON docs ->
list_events

List events from one or more Google Calendars within a time range. Auto-paginates up to 2500 results. When no calendarId is provided, queries every enabled calendar the API key can read — across every connected Google account — in parallel (one request per connection) and merges results sorted by start time.

Parameters

calendarIdstringoptionalCalendar ID. Omit to fan out across every enabled calendar this API key can read.
timeMinstringoptionalStart of time range (ISO 8601, e.g. 2026-01-01T00:00:00Z)
timeMaxstringoptionalEnd of time range (ISO 8601)
maxResultsnumberoptionalMax events to return (1-2500, default: 10). Auto-paginates internally.
querystringoptionalFree text search. Note: may not work on non-primary calendars (Google API limitation).
singleEventsbooleanoptionalExpand recurring events into instances (default: true)
orderBystringoptional"startTime" or "updated" (default: startTime)
pageTokenstringoptionalPagination token from a previous response.

Example

{
  "tool": "list_events",
  "arguments": {
    "timeMin": "2026-04-01T00:00:00Z",
    "timeMax": "2026-04-30T23:59:59Z",
    "maxResults": 50
  }
}

Returns

Array of event objects with id, summary, description, location, start, end, status, attendees, reminders, transparency, visibility, colorId, recurrence, htmlLink, organizer.

get_event

Get full details of a specific calendar event by its ID. Returns all fields including reminders, transparency, visibility, and colorId.

Parameters

calendarIdstringoptionalCalendar ID. Omit for default.
eventIdstringrequiredThe event ID to retrieve.

Example

{
  "tool": "get_event",
  "arguments": {
    "eventId": "abc123def456"
  }
}

Returns

Single event object with all fields.

create_event

Create a new calendar event with attendees, location, reminders, recurrence, transparency, visibility, and color. Uses Google Calendar-style start/end objects. Requires write permission on the target calendar. Events created on service-account-connected calendars cannot include attendees — Google does not allow service accounts to dispatch invites on personal calendars. Connect the same Google account via OAuth if you need to invite attendees.

Parameters

calendarIdstringoptionalCalendar ID. Omit for default.
summarystringrequiredEvent title.
descriptionstringoptionalEvent description.
locationstringoptionalEvent location.
startobjectrequiredGoogle Calendar start object: {dateTime, timeZone?} for timed events or {date} for all-day events.
endobjectrequiredGoogle Calendar end object: {dateTime, timeZone?} for timed events or {date} for all-day events. All-day end dates are exclusive.
attendeesstring[]optionalList of attendee email addresses.
remindersobjectoptional{ useDefault: boolean, overrides?: [{ method: "email"|"popup", minutes: number }] }
recurrencestring[]optionalRRULE format, e.g. ["RRULE:FREQ=WEEKLY;COUNT=10"]
transparencystringoptional"opaque" (busy, default) or "transparent" (free).
visibilitystringoptional"default", "public", "private", or "confidential".
colorIdstringoptionalColor ID (1-11).

Example

{
  "tool": "create_event",
  "arguments": {
    "summary": "Team Standup",
    "start": {
      "dateTime": "2026-04-20T09:00:00-07:00",
      "timeZone": "America/Denver"
    },
    "end": {
      "dateTime": "2026-04-20T09:30:00-07:00",
      "timeZone": "America/Denver"
    },
    "attendees": [
      "alice@example.com",
      "bob@example.com"
    ],
    "reminders": {
      "useDefault": false,
      "overrides": [
        {
          "method": "popup",
          "minutes": 10
        }
      ]
    }
  }
}

Returns

MCP structuredContent: { eventId, event }. content[0].text also contains a human-readable JSON summary.

update_event

Update an existing calendar event. Partial update via PATCH — only provide fields you want to change. Uses Google Calendar-style start/end objects when changing time. Requires write permission on the target calendar. Changing the attendees list on a service-account-connected calendar is rejected; reconnect the account via OAuth if you need to modify attendees.

Parameters

calendarIdstringoptionalCalendar ID. Omit for default.
eventIdstringrequiredThe event ID to update.
summarystringoptionalNew event title.
descriptionstringoptionalNew event description.
locationstringoptionalNew event location.
startobjectoptionalGoogle Calendar start object: {dateTime, timeZone?} for timed events or {date} for all-day events.
endobjectoptionalGoogle Calendar end object: {dateTime, timeZone?} for timed events or {date} for all-day events. All-day end dates are exclusive.
statusstringoptional"confirmed", "tentative", or "cancelled".
remindersobjectoptionalUse {useDefault: false, overrides: []} to suppress all reminders.
transparencystringoptional"opaque" (busy) or "transparent" (free).
visibilitystringoptional"default", "public", "private", or "confidential".
colorIdstringoptionalColor ID (1-11).
attendeesstring[]optionalReplaces existing attendees.
recurrencestring[]optionalRRULE format.

Example

{
  "tool": "update_event",
  "arguments": {
    "eventId": "abc123def456",
    "reminders": {
      "useDefault": false,
      "overrides": []
    },
    "transparency": "transparent"
  }
}

Returns

MCP structuredContent: { eventId, event }. content[0].text also contains a human-readable JSON summary.

batch_update_events

Update multiple calendar events in one call. Each update is a partial patch. Max 50 events per call. Events are updated concurrently. Uses Google Calendar-style start/end objects when changing time.

Parameters

calendarIdstringoptionalCalendar ID. Omit for default. Applies to all events in the batch.
updatesarrayrequiredArray of update objects (max 50). Each must include eventId plus fields to change. Supports: summary, description, location, start, end, status, reminders, transparency, visibility, colorId.

Example

{
  "tool": "batch_update_events",
  "arguments": {
    "updates": [
      {
        "eventId": "event1",
        "reminders": {
          "useDefault": false,
          "overrides": []
        },
        "transparency": "transparent"
      },
      {
        "eventId": "event2",
        "reminders": {
          "useDefault": false,
          "overrides": []
        },
        "transparency": "transparent"
      },
      {
        "eventId": "event3",
        "colorId": "5",
        "summary": "Updated Title"
      }
    ]
  }
}

Returns

Summary: "X succeeded, Y failed" with event IDs. Failed events include error messages.

delete_event

Delete a calendar event.

Parameters

calendarIdstringoptionalCalendar ID. Omit for default.
eventIdstringrequiredThe event ID to delete.

Example

{
  "tool": "delete_event",
  "arguments": {
    "eventId": "abc123def456"
  }
}

Returns

Confirmation message.

quick_add_event

Create an event from natural language text. Google parses the text to extract date, time, title, and location.

Parameters

calendarIdstringoptionalCalendar ID. Omit for default.
textstringrequiredNatural language event description, e.g. "Lunch with Alice tomorrow at noon at Cafe Rio".

Example

{
  "tool": "quick_add_event",
  "arguments": {
    "text": "Dentist appointment Friday at 2pm"
  }
}

Returns

Created event object.

list_calendars

List every calendar this API key can access across every connected Google account, with its enabled flag, per-calendar read/write permissions, and which kind of connection backs it (OAuth or service account).

Example

{
  "tool": "list_calendars",
  "arguments": {}
}

Returns

Array of { id, summary, enabled, canRead, canWrite, connectionKind }. Use this to discover what the key is allowed to do before attempting a tool call.

create_calendar

Create a new secondary Google Calendar on an OAuth-connected account, then add it to this API key with read/write permission. Not available for service-account-connected calendars; service-account users should create the calendar in Google Calendar first, share it with CalendarMCP, then add it from the dashboard.

Parameters

calendarIdstringoptionalExisting calendar ID on the OAuth account that should own the new calendar. Omit to use the first writable OAuth account.
summarystringrequiredCalendar name.
descriptionstringoptionalCalendar description.
locationstringoptionalCalendar location.
timeZonestringoptionalIANA time zone, e.g. America/Los_Angeles.

Example

{
  "tool": "create_calendar",
  "arguments": {
    "summary": "Project Launch",
    "timeZone": "America/Los_Angeles"
  }
}

Returns

MCP structuredContent: { calendarId, calendar }. content[0].text also contains a human-readable JSON summary.

find_free_time

Query free/busy information for one or more calendars in a time range.

Parameters

calendarIdsstring[]optionalCalendar IDs to check. Omit for default.
timeMinstringrequiredStart of time range (ISO 8601).
timeMaxstringrequiredEnd of time range (ISO 8601).

Example

{
  "tool": "find_free_time",
  "arguments": {
    "timeMin": "2026-04-21T08:00:00-07:00",
    "timeMax": "2026-04-21T18:00:00-07:00"
  }
}

Returns

Array of busy slots per calendar with start/end times.

manage_attendees

Add or remove attendees from an existing event without replacing the full attendee list.

Parameters

calendarIdstringoptionalCalendar ID. Omit for default.
eventIdstringrequiredThe event ID.
addAttendeesstring[]optionalEmail addresses to add.
removeAttendeesstring[]optionalEmail addresses to remove.

Example

{
  "tool": "manage_attendees",
  "arguments": {
    "eventId": "abc123def456",
    "addAttendees": [
      "charlie@example.com"
    ],
    "removeAttendees": [
      "dave@example.com"
    ]
  }
}

Returns

Updated event object.

Common patterns

Suppress reminders

{
  "tool": "update_event",
  "arguments": {
    "eventId": "EVENT_ID",
    "reminders": {
      "useDefault": false,
      "overrides": []
    }
  }
}

Mark event as free

{
  "tool": "update_event",
  "arguments": {
    "eventId": "EVENT_ID",
    "transparency": "transparent"
  }
}

Bulk reminder cleanup

{
  "tool": "batch_update_events",
  "arguments": {
    "updates": [
      {
        "eventId": "event1",
        "reminders": {
          "useDefault": false,
          "overrides": []
        }
      },
      {
        "eventId": "event2",
        "reminders": {
          "useDefault": false,
          "overrides": []
        }
      }
    ]
  }
}

Scan a full month

{
  "tool": "list_events",
  "arguments": {
    "timeMin": "2026-04-01T00:00:00Z",
    "timeMax": "2026-04-30T23:59:59Z",
    "maxResults": 500
  }
}