google-calendar — Claude Code MCP server: setup guide
Connects Google Calendar to your coding assistant via Google Workspace domain delegation. Read events, book meetings, and inspect free or busy schedules.
claude mcp add --env GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL=<GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL> --env GCAL_SERVICE_ACCOUNT_PRIVATE_KEY=<GCAL_SERVICE_ACCOUNT_PRIVATE_KEY> --env GCAL_IMPERSONATE_EMAIL=<GCAL_IMPERSONATE_EMAIL> --env ENABLED_TOOLGROUPS=<ENABLED_TOOLGROUPS> --transport stdio google-calendar -- npx -y google-calendar-workspace-mcp-serverWhat google-calendar does
The server routes model actions to Google Calendar API endpoints through domain-wide service account delegation. It acts on behalf of the inbox defined in GCAL_IMPERSONATE_EMAIL. Available operations cover fetching schedules, booking appointments with guest lists, updating calendar entries via PATCH, and checking open slots.
Personal Google accounts will not work here. Setup demands a Google Cloud project with the Calendar API enabled, plus admin authority over a Google Workspace domain. Without assigning the https://www.googleapis.com/auth/calendar scope to your service account client ID inside Google Workspace Admin, the connection fails immediately.
All 7 tools run active out of the box. If write operations pose a risk, set ENABLED_TOOLGROUPS=readonly in your environment. That locks the server into read-only actions, shutting down event creation, edits, and deletions.
What it helps with
- find free meeting slots across calendar schedules
- create appointments with attendee lists and descriptions
- inspect upcoming meetings within a chosen date range
- update event details without overwriting unchanged fields
Example prompts for the agent
- List all my meetings scheduled for tomorrow.
- Schedule a quick 30-minute sync with [email protected] on Friday at 2 PM.
- Check if my schedule is free on Thursday afternoon.
How to install google-calendar
Platform CLI
claude mcp add --env GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL=<GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL> --env GCAL_SERVICE_ACCOUNT_PRIVATE_KEY=<GCAL_SERVICE_ACCOUNT_PRIVATE_KEY> --env GCAL_IMPERSONATE_EMAIL=<GCAL_IMPERSONATE_EMAIL> --env ENABLED_TOOLGROUPS=<ENABLED_TOOLGROUPS> --transport stdio google-calendar -- npx -y google-calendar-workspace-mcp-serverReplace <…> with your own values
Platform CLI
codex mcp add google-calendar --env GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL=<GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL> --env GCAL_SERVICE_ACCOUNT_PRIVATE_KEY=<GCAL_SERVICE_ACCOUNT_PRIVATE_KEY> --env GCAL_IMPERSONATE_EMAIL=<GCAL_IMPERSONATE_EMAIL> --env ENABLED_TOOLGROUPS=<ENABLED_TOOLGROUPS> -- npx -y google-calendar-workspace-mcp-serverReplace <…> with your own values
Config file
{
"mcpServers": {
"google-calendar": {
"command": "npx",
"args": [
"-y",
"google-calendar-workspace-mcp-server"
],
"env": {
"GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL": "<GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL>",
"GCAL_SERVICE_ACCOUNT_PRIVATE_KEY": "<GCAL_SERVICE_ACCOUNT_PRIVATE_KEY>",
"GCAL_IMPERSONATE_EMAIL": "<GCAL_IMPERSONATE_EMAIL>",
"ENABLED_TOOLGROUPS": "<ENABLED_TOOLGROUPS>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"google-calendar": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"google-calendar-workspace-mcp-server"
],
"env": {
"GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL": "<GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL>",
"GCAL_SERVICE_ACCOUNT_PRIVATE_KEY": "<GCAL_SERVICE_ACCOUNT_PRIVATE_KEY>",
"GCAL_IMPERSONATE_EMAIL": "<GCAL_IMPERSONATE_EMAIL>",
"ENABLED_TOOLGROUPS": "<ENABLED_TOOLGROUPS>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL=<GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL> -e GCAL_SERVICE_ACCOUNT_PRIVATE_KEY=<GCAL_SERVICE_ACCOUNT_PRIVATE_KEY> -e GCAL_IMPERSONATE_EMAIL=<GCAL_IMPERSONATE_EMAIL> -e ENABLED_TOOLGROUPS=<ENABLED_TOOLGROUPS> google-calendar npx -y google-calendar-workspace-mcp-serverReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about google-calendar
How do I install google-calendar in Claude Code?
Run the command: `claude mcp add google-calendar -e GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL=<GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL> -e GCAL_SERVICE_ACCOUNT_PRIVATE_KEY=<GCAL_SERVICE_ACCOUNT_PRIVATE_KEY> -e GCAL_IMPERSONATE_EMAIL=<GCAL_IMPERSONATE_EMAIL> -- npx -y google-calendar-workspace-mcp-server`. Replace placeholder values with your JSON key details and target inbox email.
What does google-calendar do?
It connects your coding assistant to Google Workspace calendars using service account delegation, enabling automated scheduling, event updates, and availability queries.
Can I configure google-calendar as read-only?
Yes, define the ENABLED_TOOLGROUPS environment variable as readonly. The server will restrict tools so that write and delete actions cannot be called.
