# 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

## System Architecture

```mermaid
flowchart TD
    subgraph Client["🤖 MCP Client"]
        Claude["Claude Desktop<br/>(STDIO)"]
        Web["Web App / Other MCP Client<br/>(HTTP + SSE)"]
    end

    subgraph STDIO["📥 STDIO Server — server.py"]
        direction TB
        S1["mcp.server.stdio.stdio_server()"]
        S2["Server('mcp-server-google-calendar')"]
        S3["@server.list_tools()<br/>handle_list_tools()"]
        S4["@server.call_tool()<br/>handle_call_tool(name, arguments)"]
        S1 --> S2 --> S3
        S2 --> S4
    end

    subgraph SSE["🌐 SSE Server — server_sse.py"]
        direction TB
        E1["uvicorn.run(app)"]
        E2["FastMCP('Google Calendar MCP Server')"]
        E3["mcp.sse_app()<br/>/sse endpoint"]
        E4["@mcp.tool() decorated<br/>functions"]
        E1 --> E3 --> E2
        E2 --> E4
    end

    subgraph AUTH["🔐 auth/auth.py"]
        direction TB
        A1["authorize()"]
        A2{"token.json<br/>exists & valid?"}
        A3["load_saved_credentials()"]
        A4["Refresh via<br/>Request()"]
        A5["InstalledAppFlow<br/>.from_client_secrets_file(credentials.json)"]
        A6["Browser OAuth 2.0<br/>consent screen"]
        A7["save_credentials()<br/>→ token.json"]
        A1 --> A3 --> A2
        A2 -- "expired, has refresh_token" --> A4 --> A7
        A2 -- "missing/invalid" --> A5 --> A6 --> A7
        A2 -- "valid" --> Return["Return Credentials"]
        A7 --> Return
    end

    subgraph GAPI["📅 Google Calendar API v3"]
        direction TB
        Build["googleapiclient.discovery.build()"]
        Ops["events().list / insert / update / delete<br/>calendarList().list<br/>freebusy().query<br/>settings().get('timezone')"]
        Build --> Ops
    end

    subgraph TOOLS["🛠️ Validated Tool Operations — schemas.py + tools/tools.py"]
        direction LR
        T1["get-events"]
        T2["list-calendars"]
        T3["get-timezone-info"]
        T4["get-current-date"]
        T5["check-availability<br/>(conflict detection)"]
        T6["create-event"]
        T7["update-event"]
        T8["delete-event"]
    end

    Claude -->|"JSON-RPC over stdio"| S4
    Web -->|"HTTP/SSE request"| E4

    S4 -->|"Pydantic validation<br/>(ListEventsRequest, CreateEventRequest, etc.)"| TOOLS
    E4 -->|"Pydantic validation"| TOOLS

    S4 --> A1
    E4 --> A1
    Return --> Build

    TOOLS --> Build
    Ops -->|"JSON response"| S4
    Ops -->|"JSON response"| E4
    S4 -->|"TextContent result"| Claude
    E4 -->|"SSE stream result"| Web
```

**Key architectural notes:**
- Both the **STDIO** and **SSE** servers are independent implementations that share the same `auth`, `schemas`, and Google Calendar API logic, but use different MCP transports — STDIO for local Claude Desktop integration, SSE/HTTP for remote or web-based clients.
- The **authorization flow** (`authorize()`) checks for a cached `token.json`; if it's missing, invalid, or expired, it either silently refreshes the token or triggers a one-time browser-based OAuth 2.0 consent flow using `credentials.json`, then persists the resulting token for future runs.
- Every tool call is validated against a **Pydantic schema** (`schemas.py`) before hitting the Google Calendar API, and includes built-in **conflict detection** (via `freebusy().query`) for event creation/updates.

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

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

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

**Alternative using Python module:**
```json
{
  "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:

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