# 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](https://console.cloud.google.com/)
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

```bash
# 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

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

### 4. Start the Server

```bash
docker compose up -d
```

### 5. Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```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

```yaml
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