mcp-google-gcal

mcp-google-gcal

An MCP server for Google Calendar. Lets AI assistants manage events, calendars, sharing, and scheduling with full read/write access across multiple Google accounts. Supports natural language event creation, recurring events, Google Meet conferencing, free/busy queries, and ACL management.

Tools

Events

Tool	Description
gcal_list_events	List events with time range, search, pagination, and event type filtering
gcal_get_event	Get full event details by ID
gcal_create_event	Create event with attendees, recurrence, Google Meet, attachments, and more
gcal_update_event	Update event fields using patch semantics
gcal_delete_event	Delete event with notification control
gcal_quick_add	Create event from natural language text
gcal_move_event	Move an event from one calendar to another
gcal_list_instances	List individual occurrences of a recurring event
gcal_import_event	Import event from external system preserving iCalUID

Calendars

Tool	Description
gcal_list_calendars	List all calendars on the user's calendar list
gcal_get_calendar	Get calendar metadata (summary, description, timezone)
gcal_create_calendar	Create a new secondary calendar
gcal_update_calendar	Edit calendar metadata using patch semantics
gcal_delete_calendar	Delete a secondary calendar
gcal_clear_calendar	Clear all events from the primary calendar (irreversible)

Calendar List (User Preferences)

Tool	Description
gcal_get_calendar_list_entry	Get a calendar's list-level settings (color, reminders, notifications)
gcal_subscribe_calendar	Add an existing calendar to the user's calendar list
gcal_update_calendar_list_entry	Update color, reminders, or notification preferences
gcal_unsubscribe_calendar	Remove a calendar from the user's list (does not delete it)

Access Control (Sharing)

Tool	Description
gcal_list_acl	List sharing permissions on a calendar
gcal_add_acl	Share a calendar with a user, group, or domain
gcal_update_acl	Change the sharing role for an existing rule
gcal_remove_acl	Revoke a sharing rule

Utilities

Tool	Description
gcal_list_settings	List user calendar settings (timezone, locale, format preferences)
gcal_get_colors	Get color definitions for calendars and events
gcal_freebusy	Query free/busy information for calendars and groups

Output Formats

All read and list tools support an outputFormat parameter:

Format	Description	Use Case
json	Pretty-printed JSON (default)	Machine consumption, API pipelines
yaml	YAML serialization	Human-readable structured data
text	Compact aligned tables and key-value pairs	Quick scanning, token-efficient LLM context

Prerequisites

• Node.js 18+
• A Google Cloud project with the Google Calendar API enabled
• OAuth2 desktop application credentials

Setup

• Create or use an existing project in the Google Cloud Console and enable the Google Calendar API
• Create OAuth2 credentials (Application type: Desktop app) and download the JSON file
• Save the credentials file:

mkdir -p ~/.config/mcp-google-gcal
cp ~/Downloads/client_secret_*.json ~/.config/mcp-google-gcal/credentials.json

• Run the one-time authorization flow:

npx mcp-google-gcal --auth primary

This prints a URL for Google consent. After granting access, paste the authorization code back into the terminal.

Multi-Account Setup

Add additional accounts with unique labels:

npx mcp-google-gcal --auth work
npx mcp-google-gcal --auth personal

Pass the account parameter to any tool to specify which account to use.

MCP Client Configuration

Claude Code

claude mcp add -s user google-gcal -- npx -y mcp-google-gcal

VS Code / Cursor

{
  "mcpServers": {
    "google-gcal": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-gcal"]
    }
  }
}

Gemini CLI

{
  "mcpServers": {
    "google-gcal": {
      "command": "npx",
      "args": ["-y", "mcp-google-gcal"]
    }
  }
}

License

MIT