Google Calendar MCP Setup Guide

Set up Google Calendar integration for Claude Code CLI using the @cocal/google-calendar-mcp server.

Source: https://github.com/nspady/google-calendar-mcp

Prerequisites

• Node.js installed (for npx)

• Google account

• Claude Code CLI installed

Part 1: Google Cloud Console Setup

Step 1: Create Project

• Go to https://console.cloud.google.com/

• Click project dropdown (top-left) → New Project

• Name: Claude Calendar → Create

• Select the new project from dropdown

Step 2: Enable Calendar API

• Go to APIs & Services → Library

• Search "Google Calendar API" → Click → Enable

Step 3: OAuth Consent Screen

• Go to APIs & Services → OAuth consent screen

• Select External → Create

• Fill required fields:

• App name: Claude Calendar

• User support email: (your email)

• Developer contact: (your email)

• Click Save and Continue

• Scopes page → Add or Remove Scopes

• Add: https://www.googleapis.com/auth/calendar

• Click Update → Save and Continue

• Test Users → Add Users → Add your Gmail → Save and Continue

Step 4: Create Credentials

• Go to APIs & Services → Credentials

• Click + Create Credentials → OAuth client ID

• Application type: Desktop app

• Name: Claude Code

• Click Create → Download JSON

Part 2: Save Credentials

Save the downloaded JSON file:

Windows:

C:\Users\salmanferoz.google-calendar-mcp\gcp-oauth.keys.json

Mac/Linux:

~/.google-calendar-mcp/gcp-oauth.keys.json

Create the .google-calendar-mcp folder if it doesn't exist.

Part 3: Add MCP to Claude Code

Auto-Setup Command

When the user has saved their credentials, run this command automatically:

Windows:

claude mcp add --scope user --transport stdio google-calendar --env GOOGLE_OAUTH_CREDENTIALS="C:\Users\salmanferoz.google-calendar-mcp\gcp-oauth.keys.json" -- npx -y @cocal/google-calendar-mcp

Mac/Linux:

claude mcp add --scope user --transport stdio google-calendar --env GOOGLE_OAUTH_CREDENTIALS="$HOME/.google-calendar-mcp/gcp-oauth.keys.json" -- npx -y @cocal/google-calendar-mcp

Manual JSON Config (Alternative)

Add to ~/.claude.json :

{ "mcpServers": { "google-calendar": { "type": "stdio", "command": "npx", "args": ["-y", "@cocal/google-calendar-mcp"], "env": { "GOOGLE_OAUTH_CREDENTIALS": "/path/to/.google-calendar-mcp/gcp-oauth.keys.json" } } } }

Part 4: First Authorization

• Restart Claude Code: claude

• Ask: "What's on my calendar today?"

• Browser opens → Sign in with Google

• Click Continue (ignore "unverified app" warning)

• Grant calendar permissions

• Token saved automatically to .google-calendar-mcp/token.json

Available Tools

Tool Description

list-calendars Enumerate available calendars

list-events Retrieve events with date filtering

get-event Fetch specific event details by ID

search-events Query events by text

create-event Add new calendar events

update-event Modify existing events

delete-event Remove events

respond-to-event Accept/decline/maybe invitations

get-freebusy Check cross-calendar availability

get-current-time Retrieve current date/time in timezone

list-colors View available event colors

manage-accounts Add/list/remove Google accounts

Features

Feature Description

Multi-Account Connect multiple Google accounts

Multi-Calendar Query multiple calendars at once

Conflict Detection Find overlapping events across accounts

Full CRUD Create, read, update, delete events

Recurring Events Manage recurring event patterns

Free/Busy Check availability across calendars

Natural Language Schedule events using natural language

Event Import Import events from images/PDFs/web links

Environment Variables

Variable Description

GOOGLE_OAUTH_CREDENTIALS Path to OAuth credentials file (required)

GOOGLE_CALENDAR_MCP_TOKEN_PATH Custom token storage location (optional)

MCP Management Commands

List configured servers

claude mcp list

Check status (inside Claude Code)

/mcp

Remove server

claude mcp remove google-calendar

Get server details

claude mcp get google-calendar

Troubleshooting

Issue Solution

"Credentials not found" Check GOOGLE_OAUTH_CREDENTIALS path is correct

"Access denied" Add your email as test user in OAuth consent screen

"API not enabled" Enable Google Calendar API in Cloud Console

Token expired Delete token.json and re-authorize

Weekly re-auth required Publish app to production mode in Cloud Console

File Locations Summary

File Purpose Location

gcp-oauth.keys.json OAuth credentials ~/.google-calendar-mcp/

token.json Auth token (auto-created) ~/.google-calendar-mcp/

~/.claude.json Claude Code config User home directory