wanthigh/google-calendar-mcp-server

Google Calendar MCP Server

A Model Context Protocol (MCP) server for Google Calendar integration with Claude Desktop. Create, update, delete, and manage calendar events with batch operations and enterprise-grade retry mechanisms.

🚀 Quick Start

1. Install

npm install -g github:wanthigh/google-calendar-mcp-server

2. Set up Google Calendar API

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable Google Calendar API
4. Create credentials:
   • Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs"
   • Choose "Desktop application"
   • Download the JSON file

3. Configure

Create a folder for your config files and save your credentials:

mkdir ~/.google-calendar-mcp
# Save your downloaded credentials.json to ~/.google-calendar-mcp/credentials.json

4. Add to Claude Desktop or Claude Code

For Claude Desktop

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-calendar": {
      "command": "google-calendar-mcp",
      "args": ["--credentials", "/Users/YOUR_USERNAME/.google-calendar-mcp/credentials.json"]
    }
  }
}

For Claude Code

Edit your Claude Code global config file:

All platforms: ~/.claude.json

{
  "mcpServers": {
    "google-calendar": {
      "command": "google-calendar-mcp",
      "args": ["--credentials", "/Users/YOUR_USERNAME/.google-calendar-mcp/credentials.json"]
    }
  }
}

Note: On Windows, replace /Users/YOUR_USERNAME/ with C:\Users\YOUR_USERNAME\

5. First Run

Restart Claude Desktop. The first time you use a calendar function, you'll be prompted to authorize access through your browser.

Note: If you need to manually authorize (rare), you can run:

google-calendar-mcp --credentials /Users/YOUR_USERNAME/.google-calendar-mcp/credentials.json

✨ Features

• Single Operations: Create, update, delete, list, and search events
• Batch Operations: Process multiple events efficiently
• Smart Retry: Automatic retry with exponential backoff for API failures
• Rate Limiting: Built-in protection against quota exhaustion
• Authentication: OAuth2 and Service Account support

🛠️ Available Tools

Basic Operations

• create_event - Create a new calendar event
• update_event - Update an existing event
• delete_event - Delete an event
• list_events - List events in a time range
• search_events - Search events by keyword

Batch Operations

• batch_create_events - Create multiple events
• batch_update_events - Update multiple events
• batch_delete_events - Delete multiple events

🔧 Example Usage in Claude

"Create a meeting tomorrow at 2pm called 'Team Sync'"

"List all my events for next week"

"Delete the event with ID abc123"

"Create 5 training sessions every Monday at 10am for the next month"

🐛 Troubleshooting

"Authentication failed"

• Check your credentials.json file path
• Complete the OAuth authorization in your browser

"Calendar not found"

• Make sure you're using the correct calendar ID
• For service accounts, share your calendar with the service account email

"Rate limit exceeded"

• The server has built-in retry mechanisms
• Reduce batch sizes if needed

📞 Support

• GitHub Issues
• Documentation

📄 License

MIT License

Version: 1.0.1 | Author: @wanthigh