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

1. Go to https://console.cloud.google.com/
2. Click project dropdown (top-left) → New Project
3. Name: Claude Calendar → Create
4. Select the new project from dropdown

Step 2: Enable Calendar API

1. Go to APIs & Services → Library
2. Search "Google Calendar API" → Click → Enable

Step 3: OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Select External → Create
3. Fill required fields:
   • App name: Claude Calendar
   • User support email: (your email)
   • Developer contact: (your email)
4. Click Save and Continue
5. Scopes page → Add or Remove Scopes
   • Add: https://www.googleapis.com/auth/calendar
   • Click Update → Save and Continue
6. Test Users → Add Users → Add your Gmail → Save and Continue

Step 4: Create Credentials

1. Go to APIs & Services → Credentials
2. Click + Create Credentials → OAuth client ID
3. Application type: Desktop app
4. Name: Claude Code
5. 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

1. Restart Claude Code: claude
2. Ask: "What's on my calendar today?"
3. Browser opens → Sign in with Google
4. Click Continue (ignore "unverified app" warning)
5. Grant calendar permissions
6. 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 |