mcp-google-calendar

guinacio/mcp-google-calendar

3.2

If you are the rightful owner of mcp-google-calendar and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server that allows AI assistants to interact with Google Calendar for managing events, checking availability, and handling scheduling tasks.

Google Calendar MCP Server

A Model Context Protocol (MCP) server that allows Claude and other MCP clients to interact with Google Calendar. This server enables AI assistants to manage your calendar events, check availability, and handle scheduling tasks.

Features

Calendar Management

  • List Events (get-events)

    • View events from any calendar
    • Filter by time range
    • Limit number of results

  • List Calendars (list-calendars)

    • View all available calendars
    • Access calendar IDs and settings

  • Get Timezone Info (get-timezone-info)

    • Get user's timezone information

  • Get Current Date (get-current-date)

    • Get current date and time in user's timezone
    • Useful for AI models with outdated knowledge cutoff dates

Event Operations

  • Create Events (create-event)

    • Schedule new events with full feature support
    • Add attendees and set reminders
    • Include conference links and attachments
    • Set visibility, transparency, and colors
    • Configure recurring events
    • Automatic timezone detection and conflict checking

  • Update Events (update-event)

    • Modify existing events
    • Change time/date with conflict checking
    • Add/remove attendees
    • Update any event details
    • Control notification settings

  • Delete Events (delete-event)

    • Remove events from calendar
    • Control notification settings for attendees

Availability Management

  • Check Availability (check-availability)
    • Check free/busy status for multiple calendars
    • Time zone awareness
    • Support for checking other users' availability

Requirements

  • Python >= 3.12
  • Google Cloud Console Project with Calendar API enabled
  • OAuth 2.0 credentials

Installation

1. Set up Google Cloud Project

  1. Go to Google Cloud Console
  2. Create a new project or select existing one
  3. Enable Google Calendar API
  4. Create OAuth 2.0 credentials (Desktop Application type)
  5. Download credentials and save as credentials.json in the \mcp_server_google_calendar folder

2. Install the Package

# Clone or download the project
cd mcp-google-calendar

# Install the package
pip install -e .

3. Authentication Setup

On first run, the server will automatically open your browser for OAuth authentication. Your credentials will be saved for future use.

Usage

This server can run in two modes:

STDIO Mode (for Claude Desktop)

Configure Claude Desktop:

Add the following to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "google_calendar": {
      "command": "mcp-server-google-calendar"
    }
  }
}

Alternative using Python module:

{
  "mcpServers": {
    "google_calendar": {
      "command": "python",
      "args": ["-m", "mcp_server_google_calendar"]
    }
  }
}

Restart Claude Desktop after configuration changes.

SSE Mode (for web applications and other clients)

Run the server with SSE transport:

# Using the installed command
mcp-server-google-calendar-sse

# Or using Python module
python -m mcp_server_google_calendar.server_sse

# With custom host/port
python -m mcp_server_google_calendar.server_sse --host 0.0.0.0 --port 8001

The SSE server will be available at:

  • Server: http://localhost:8000
  • SSE Endpoint: http://localhost:8000/sse

Example Commands

Here are some things you can ask Claude:

Event Creation

  • "Create an event called 'Team Meeting' for tomorrow at 2pm"
  • "Schedule a recurring meeting every Monday at 10am"
  • "Set up a video call with John for next Tuesday afternoon"

Event Management

  • "Move my 2pm meeting to 4pm"
  • "Add Jane (jane@example.com) to tomorrow's team meeting"
  • "Cancel my meeting with John"
  • "Update the location of today's team lunch"

Calendar Queries

  • "What meetings do I have this week?"
  • "When am I free tomorrow afternoon?"
  • "Check if both Alice and Bob are available next Monday at 3pm"
  • "List all my recurring events"

Date/Time Information

  • "What's today's date?" (useful for models with outdated knowledge)
  • "What day of the week is it?"
  • "What's my current timezone?"

Advanced Features

Time Conflict Detection

The server automatically checks for time conflicts when creating or updating events and will warn you about overlapping events.

Timezone Support

  • Automatic timezone detection from your Google Calendar settings
  • Manual timezone specification for events
  • Proper handling of timezone conversions

Recurring Events

Full support for recurring events using iCalendar RRULE format:

  • Daily, weekly, monthly, yearly patterns
  • Custom recurrence rules
  • Exception dates and rules

Attendee Management

  • Add/remove attendees with email validation
  • Set optional vs required attendees
  • Control response status and notifications
  • Support for additional guests

Troubleshooting

Authentication Issues

  • Ensure credentials.json is in the project root directory
  • Check if OAuth consent screen is configured in Google Cloud Console
  • Verify Calendar API is enabled
  • Delete token.json to force re-authentication if needed

Server Connection Issues

  • Verify Python version (>= 3.12 required)
  • Check Claude Desktop configuration file syntax
  • Restart Claude Desktop after configuration changes
  • For SSE mode, ensure the port is not in use

Event Creation Problems

  • Confirm calendar permissions in Google Calendar
  • Check for time conflicts with existing events
  • Verify attendee email addresses are valid
  • Ensure timezone format is correct

File Structure

mcp-google-calendar/
ā”œā”€ā”€ mcp_server_google_calendar/
ā”‚   ā”œā”€ā”€ __init__.py
ā”‚   ā”œā”€ā”€ __main__.py          # STDIO mode entry point
ā”‚   ā”œā”€ā”€ __main_sse__.py      # SSE mode entry point
ā”‚   ā”œā”€ā”€ credentials.json      # Google OAuth credentials (you provide)
ā”‚   ā”œā”€ā”€ server.py            # STDIO server implementation
ā”‚   ā”œā”€ā”€ server_sse.py        # SSE server implementation
ā”‚   ā”œā”€ā”€ schemas.py           # Pydantic schemas
ā”‚   ā”œā”€ā”€ auth/                # Authentication module
ā”‚   ā”œā”€ā”€ tools/               # Tool definitions
ā”‚   ā””ā”€ā”€ utils/               # Utility functions
ā”œā”€ā”€ token.json              # Saved auth token (auto-generated)
ā”œā”€ā”€ pyproject.toml          # Project configuration
ā””ā”€ā”€ README.md

Notes

  • The server maintains separate implementations for STDIO and SSE modes with identical features
  • Both modes support automatic timezone detection and conflict checking
  • All times should be specified in YYYY-MM-DDTHH:MM:SS format or RFC3339
  • Calendar ID 'primary' refers to the user's default calendar
  • Event updates maintain existing data for unspecified fields
  • The server automatically handles timezone detection and conversion

License

MIT License