Skip to main content
Glama
Sign In
Google Calendar MCP Server

Google Calendar MCP Server

by murphy360
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Google Calendar MCP Server

A Model Context Protocol (MCP) server for Google Calendar integration, designed for personal calendar management with Home Assistant support.

Features

  • MCP Tools: Search events, list upcoming events, create/update/delete events

  • Daily Agenda: Get formatted daily agenda summaries

  • Calendar Categories: Organize calendars by type (work, personal, family, etc.)

  • REST API: Endpoints for Home Assistant integration

  • SSE Transport: Connect from Claude Desktop via mcp-remote

  • Docker Support: Easy deployment with Docker Compose

Related MCP server: Google Calendar MCP Server

Quick Start

1. Google Cloud Setup

  1. Go to Google Cloud Console

  2. Create a new project or select existing

  3. Enable the Google Calendar API

  4. Create OAuth 2.0 credentials (Desktop App type)

  5. Download the credentials

2. Configuration

# Copy example environment file
cp .env.example .env

# Edit with your credentials
# GOOGLE_CLIENT_ID=your-client-id
# GOOGLE_CLIENT_SECRET=your-client-secret

3. Initial OAuth Setup

# Run OAuth setup (opens browser for consent)
docker compose --profile setup run --rm calendar-auth

4. Start the Server

docker compose up -d

5. Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "calendar": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://YOUR_SERVER_IP:8002/mcp/sse", "--allow-http"]
    }
  }
}

Home Assistant MCP Integration

The server exposes SSE endpoints for MCP connections:

  • /mcp/sse - Primary MCP SSE endpoint

  • /sse - Alias endpoint for Home Assistant compatibility

Each connection gets a fresh server instance for proper session isolation.

MCP Tools

Tool

Description

calendar_get_current_time

Get current date/time with reference dates for queries

calendar_list_events

List upcoming events with optional filters

calendar_search

Search events by text query

calendar_get_event

Get details of a specific event

calendar_create_event

Create a new calendar event

calendar_update_event

Update an existing event

calendar_delete_event

Delete an event

calendar_daily_agenda

Get agenda for a specific day

calendar_weekly_summary

Get 7-day overview

calendar_list_calendars

List all available calendars

calendar_free_busy

Check availability for a time range

Tool Schema Notes

All tools use Gemini-compatible schemas with explicit types:

  • Array parameters use comma-separated strings (e.g., attendees: "user1@example.com,user2@example.com")

  • Calendar IDs use comma-separated strings (e.g., calendar_ids: "primary,work@group.calendar.google.com")

  • Dates use ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)

REST API Endpoints

Endpoint

Description

GET /health

Health check with auth status

GET /calendars

List all calendars

GET /events/today

Today's events

GET /events/upcoming

Upcoming events

GET /events/search?q=query

Search events

GET /summary/daily

Daily summary

GET /summary/weekly

Weekly summary

GET /free-time

Find free time slots

Home Assistant Integration

REST Sensor Example

sensor:
  - platform: rest
    name: "Next Calendar Event"
    resource: http://YOUR_SERVER_IP:8002/events/upcoming?days=1
    value_template: "{{ value_json[0].summary if value_json else 'No events' }}"
    scan_interval: 300

  - platform: rest
    name: "Today's Events Count"
    resource: http://YOUR_SERVER_IP:8002/events/today
    value_template: "{{ value_json | length }}"
    scan_interval: 300

MCP Integration

Home Assistant can connect via the MCP SSE endpoints:

  • http://YOUR_SERVER_IP:8002/mcp/sse

  • http://YOUR_SERVER_IP:8002/sse (alias)

Project Structure

mcp_google_calendar/
├── src/mcp_google_calendar/
│   ├── __init__.py
│   ├── auth.py              # OAuth2 authentication
│   ├── calendar_client.py   # Google Calendar API wrapper
│   ├── config.py            # Settings and configuration
│   ├── models.py            # Pydantic models
│   ├── server.py            # MCP stdio server
│   ├── sse_server.py        # MCP SSE server
│   ├── combined_server.py   # REST + SSE combined server
│   └── api.py               # REST API for Home Assistant
├── config/
│   └── calendars.yaml       # Calendar categorization
├── credentials/
│   ├── client_secrets.json  # OAuth credentials
│   └── token.json           # Stored tokens
├── docker-compose.yml
├── Dockerfile
└── README.md

License

MIT

Available Tools

11 tools
calendar_create_eventA

Create a new calendar event.

Creates an event with the specified details. At minimum, requires a title and start time. End time defaults to one hour after start if not provided.

Inputs: summary (required), start_time (required), end_time, description, +4 more.

calendar_daily_agendaA

Get the agenda for a specific day with all events.

Returns a formatted summary of all events for the specified date, organized by all-day events and timed events. Useful for daily briefings.

Inputs: date, calendar_ids.

calendar_delete_eventB

Delete a calendar event.

Permanently removes an event from the calendar. Optionally notifies attendees about the cancellation.

Inputs: event_id (required), calendar_id, notify_attendees.

calendar_free_busyB

Check free/busy status for a time range.

Returns busy time slots within the specified range for one or more calendars. Useful for finding available meeting times.

Inputs: start_time (required), end_time (required), calendar_ids.

calendar_get_current_timeA

Get the current date and time in the user's timezone.

Use this tool to understand what 'today', 'tomorrow', 'this week' means before making calendar queries. Returns current time, date, and reference dates for the week.

Inputs: no named parameters.

calendar_get_eventA

Get detailed information about a specific calendar event.

Returns full event details including title, description, start/end times, location, attendees, and meeting links. Requires the event ID.

Inputs: event_id (required), calendar_id.

calendar_list_calendarsB

List all available calendars.

Returns a list of all calendars accessible to the authenticated user, including their IDs, names, and whether they are the primary calendar.

Inputs: no named parameters.

calendar_list_eventsA

List upcoming calendar events within a date range.

Returns events from a specific calendar with details including title, time, location, and meeting links. Use days_ahead to control how far into the future to search.

Inputs: days_ahead, calendar_id, max_results.

calendar_searchB

Search calendar events by text query.

Searches event titles, descriptions, and locations for matching text. Can search both past and future events by specifying days_back and days_ahead.

Inputs: query (required), days_ahead, days_back, max_results.

calendar_update_eventB

Update an existing calendar event.

Modifies one or more fields of an existing event. Only provide the fields you want to change; unspecified fields remain unchanged.

Inputs: event_id (required), summary, start_time, end_time, +3 more.

calendar_weekly_summaryA

Get a summary of events for the upcoming 7 days.

Returns a week overview with events organized by day, total event count, and busiest day indicator. Useful for weekly planning.

Inputs: start_date, calendar_ids.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.9/5.0

    Scored across 11 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose with no ambiguity. For example, calendar_create_event, calendar_get_event, calendar_update_event, and calendar_delete_event form a complete CRUD set for events, while calendar_daily_agenda, calendar_weekly_summary, calendar_list_events, and calendar_search provide different querying perspectives. Tools like calendar_free_busy and calendar_get_current_time serve unique utility functions that don't overlap with others.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with the 'calendar_' prefix, such as calendar_create_event, calendar_list_events, and calendar_update_event. This uniformity makes the tool set predictable and easy to navigate, with no deviations in naming conventions across all 11 tools.

    Tool Count5/5

    With 11 tools, the server is well-scoped for Google Calendar operations. Each tool earns its place by covering essential aspects like event management (create, get, update, delete), querying (list, search, agenda, summary), and utilities (free/busy, current time, list calendars), avoiding both bloat and gaps.

    Completeness5/5

    The tool surface provides complete coverage for the Google Calendar domain. It includes full CRUD operations for events, comprehensive querying tools (daily agenda, weekly summary, list events, search), and supporting utilities (free/busy checks, current time reference, calendar listing). There are no obvious gaps, ensuring agents can handle all common calendar workflows without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers