Google Calendar MCP Server

Exposes Google Calendar as 12 MCP-style tools (list, get, create, update, delete, search, free/busy, list calendars, today, upcoming, quick-add, info) that AI agents and automations can drive through this actor. It authenticates to the Google Calendar API v3 with a Google service account (full read/write) or an API key (read-only), executes the tool call(s) you pass in the input, and writes the results to the run's dataset.

How it runs: this actor invokes tools per-run from the input (toolCall / toolCalls) and stores their JSON responses in the dataset. It is a batch tool-runner — it does not open a persistent MCP wire-protocol socket / Standby endpoint that an external MCP client connects to. See Limitations.

Input

Run a single tool:

{
    "credentialsJson": "{ ... service account JSON ... }",
    "calendarId": "primary",
    "timezone": "America/New_York",
    "toolCall": {
        "name": "calendar_today",
        "arguments": {}
    }
}

Run several tools in sequence with toolCalls (array of { "name", "arguments" }):

{
    "credentialsJson": "{ ... service account JSON ... }",
    "toolCalls": [
        { "name": "calendar_list_calendars", "arguments": {} },
        { "name": "calendar_upcoming", "arguments": { "count": 5 } }
    ]
}

Input fields

Field	Type	Required	Description
credentialsJson	string (secret)	one of creds	Google service account JSON key (full read/write). Raw JSON or base64-encoded.
apiKey	string (secret)	one of creds	Google API key (read-only; public calendars only). Used only if credentialsJson is absent/invalid.
calendarId	string	no	Calendar to operate on. Default primary. Use the calendar's email address for shared calendars.
timezone	string	no	IANA timezone for created/updated timed events (e.g. America/New_York). Default UTC.
toolCall	object	no	A single { "name", "arguments" } tool call.
toolCalls	array	no	Multiple { "name", "arguments" } tool calls run in order.

If no toolCall/toolCalls is given, the actor still authenticates and emits a server-info record describing the available tools and capabilities.

Tools (12)

Optional calendar_id overrides the run's calendarId for that call. Dates/times are ISO 8601 strings (e.g. 2026-07-11T15:00:00Z); all_day events use plain dates (e.g. 2026-07-11).

Tool	Arguments	Returns
calendar_list_events	time_min?, time_max?, max_results? (default 50), calendar_id?	{ success, calendar, count, events[] }
calendar_get_event	event_id (required), calendar_id?	{ success, ...event }
calendar_create_event	summary, start, end (required), description?, location?, attendees? (list of emails), all_day?, calendar_id?, timezone?	{ success, id, summary, html_link, start }
calendar_update_event	event_id (required), summary?, start?, end?, description?, location?, calendar_id?	{ success, id, summary, updated }
calendar_delete_event	event_id (required), calendar_id?	{ success, deleted }
calendar_search	query (required), time_min?, max_results? (default 20), calendar_id?	{ success, query, count, events[] }
calendar_free_busy	time_min, time_max (required), calendars? (list of IDs)	{ success, time_range, calendars{ id: { busy_slots, busy[] } } }
calendar_list_calendars	—	{ success, calendars[{ id, summary, primary, access_role, time_zone }], count }
calendar_today	calendar_id?	{ success, calendar, count, events[] } (today only)
calendar_upcoming	count? (default 10), calendar_id?	{ success, calendar, count, events[] }
calendar_create_quick	text (required), calendar_id?	{ success, id, summary, html_link, start }
calendar_info	—	{ success, version, stats, tools_available, authenticated, calendar_id, timezone }

Each event in an events[] array is normalized to: id, summary, description, location, start, end, all_day, status, organizer, attendees[{ email, name, status }], hangout_link, html_link, recurring.

Create / update / delete / quick-add are write operations and require service-account credentials. calendar_info responds even without authentication; every other tool returns { "success": false, "error": "Not authenticated. Provide credentialsJson." } when no valid credentials are supplied.

Output (dataset)

Each run pushes JSON records to the default dataset:

• One mcp_server_info record — name, version, tools, tool_count, authenticated, capabilities.
• One tool_result record per executed tool — type, tool, arguments, result.
• One session_stats record — stats (total_operations, reads, writes, errors).

Setup

1. Create a Google Cloud project.
2. Enable the Google Calendar API.
3. Create a service account and download its JSON key.
4. Share your calendar with the service account's email address (Google Calendar → Settings → Settings for my calendars → your calendar → Share with specific people → add the service account email). Grant Make changes to events for write access.
5. Pass the JSON key as credentialsJson (raw JSON or base64-encoded).

The actor requests the scopes calendar and calendar.events.

For read-only access to a public calendar you can instead pass an apiKey (Google API keys cannot read private calendars or perform writes).

Limitations

• Requires Google credentials. Without a valid service account (or API key), only calendar_info returns data; all other tools return a "Not authenticated" error.
• Service accounts own no calendars. The target calendar must be explicitly shared with the service account's email, or the actor cannot see or modify its events.
• API key auth is read-only and public-only. Private calendar reads and all write operations (create/update/delete/quick-add) require a service account.
• Google API quotas & rate limits apply. Heavy use can hit Calendar API quota/rate errors; these surface as { "success": false, "error": ... } in the tool result rather than crashing the run.
• Not a live MCP server. Tools are executed from the run input (toolCall/toolCalls) and results are written to the dataset. There is no persistent MCP/Standby socket for an external MCP client to connect to; each run is a one-shot batch of tool calls.
• Timezone / recurrence handling is thin. Timed events without an explicit timezone argument use the run's timezone input (default UTC); all_day events use plain dates. Reads expand recurring events (singleEvents=true) and flag them with a recurring boolean, but the actor does not author or edit RRULE recurrence rules directly.
• calendar_create_quick uses Google's natural-language parser (quickAdd); parsing accuracy of strings like "Meeting tomorrow at 3pm" is Google's, not the actor's.
• Default time windows. calendar_search, calendar_list_events, and calendar_upcoming default their lower time bound to "now" onward unless you pass time_min.

Pricing

This actor runs on the Apify platform; cost depends on the compute (memory × time) each run consumes. Google Calendar API usage itself is free within Google's standard quotas.