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

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