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

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

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

1. 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