gcalendar-mcp

Google Calendar MCP Server

An MCP (Model Context Protocol) server for managing Google Calendar reminders with support for time-based and location-based triggers.

Features

• Time-based reminders: "Remind me tomorrow at 9am to call mom"
• Location-based reminders: "Remind me to go to store X when I'm near Hashalom street in Tel Aviv"
• List reminders: View upcoming reminders
• Delete reminders: Remove reminders by ID

Prerequisites

• Python 3.11+
• uv package manager
• Google Cloud project with Calendar API enabled

Setup

1. Install dependencies

uv sync

2. Set up Google Cloud credentials

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Calendar API:

• Go to "APIs & Services" > "Library"
• Search for "Google Calendar API"
• Click "Enable"

1. Create OAuth 2.0 credentials:

• Go to "APIs & Services" > "Credentials"
• Click "Create Credentials" > "OAuth client ID"
• Choose "Desktop app" as the application type
• Download the credentials JSON file

1. Save the credentials file:

   mkdir -p ~/.config/gcalendar-mcp
   mv ~/Downloads/client_secret_*.json ~/.config/gcalendar-mcp/credentials.json

3. First-time authentication

Run the server once to authenticate:

uv run gcalendar-mcp

This will open a browser window for Google OAuth. After authorizing, your credentials will be saved.

Usage with Claude Code

Add to your Claude Code MCP configuration (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gcalendar": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/gcalendar_mcp", "gcalendar-mcp"]
    }
  }
}

Available Tools

create_time_reminder

Create a time-based reminder.

Parameters:

• title (required): What to be reminded about
• time (required): When to remind (natural language supported)
• description (optional): Additional notes

Examples:

• "remind me tomorrow at 9 to call mom"
• "remind me in 2 hours to take a break"
• "remind me today at 3pm to join the meeting"

create_location_reminder

Create a location-based reminder.

Parameters:

• title (required): What to be reminded about
• location (required): The location/address
• description (optional): Additional notes
• date (optional): Date for the reminder

Examples:

• "remind me to buy milk when near the grocery store"
• "remind me to go to store X when I'm near Hashalom street in Tel Aviv"

Note: Google Calendar doesn't natively support location-based triggers. This creates an event with the location noted. For automatic location notifications, use Google Maps or a dedicated location reminder app.

list_reminders

List upcoming reminders from the calendar.

Parameters:

• max_results (optional): Maximum number of results (default: 10)

delete_reminder

Delete a reminder by its event ID.

Parameters:

• event_id (required): The ID of the event to delete

Configuration

You can customize the credentials directory by setting the environment variable:

export GCALENDAR_MCP_CONFIG_DIR=/path/to/custom/config

Development

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest

License

MIT