MCP 服务器

Google Calendar MCP Server

Integrates Google Calendar with the Model Context Protocol to manage events, search agendas, and check availability. It features Home Assistant integration and SSE support for remote access through Claude Desktop.

README

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

Go to Google Cloud Console
Create a new project or select existing
Enable the Google Calendar API
Create OAuth 2.0 credentials (Desktop App type)
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