# Google Calendar MCP Server

A Model Context Protocol (MCP) server that provides access to Google Calendar.

## Features

- List calendar events within a time range
- Get details of specific events
- Search events by text query
- Create new calendar events
- List all accessible calendars

## Setup Instructions

### 1. Get Google Calendar API Credentials

1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the Google Calendar API:
   - Navigate to "APIs & Services" > "Library"
   - Search for "Google Calendar API"
   - Click "Enable"
4. Create OAuth 2.0 credentials:
   - Go to "APIs & Services" > "Credentials"
   - Click "Create Credentials" > "OAuth client ID"
   - Select "Desktop app" as the application type
   - Download the credentials JSON file
5. Save the credentials file as `~/.config/google-calendar-mcp/credentials.json`

### 2. Install Dependencies

```bash
pip install -r requirements.txt
```

### 3. Configure MCP

Add this to your MCP configuration file (usually `~/.config/mcp/config.json` or similar):

```json
{
  "mcpServers": {
    "google-calendar": {
      "command": "python",
      "args": ["/path/to/google-calendar-mcp/server.py"]
    }
  }
}
```

### 4. First Run - Authentication

On the first run, the server will:
1. Open a browser window for Google OAuth authentication
2. Ask you to grant calendar access permissions
3. Save the authentication token to `~/.config/google-calendar-mcp/token.json`

Future runs will use the saved token automatically.

## Docker Deployment

You can run the Google Calendar MCP Server in Docker for easier deployment and isolation. See **[DOCKER.md](DOCKER.md)** for comprehensive Docker setup instructions.

**Quick Start:**
1. Authenticate locally first (one-time): `python server.py`
2. Build and run: `docker-compose build && docker-compose up -d`
3. Configure your MCP client to use: `docker exec -i google-calendar-mcp python -u server.py`

See DOCKER.md for detailed instructions, troubleshooting, and advanced configurations.

## Available Tools

### list_events
List calendar events for a specified time range.

**Parameters:**
- `time_min` (optional): Start time in ISO format (defaults to now)
- `time_max` (optional): End time in ISO format (defaults to end of today)
- `max_results` (optional): Maximum number of events (default: 10, max: 250)
- `calendar_id` (optional): Calendar ID to query (default: 'primary')

**Example:**
```json
{
  "time_min": "2026-01-22T00:00:00Z",
  "time_max": "2026-01-22T23:59:59Z",
  "max_results": 20
}
```

### get_event
Get details of a specific calendar event.

**Parameters:**
- `event_id` (required): The event ID
- `calendar_id` (optional): Calendar ID (default: 'primary')

### search_events
Search for calendar events by text query.

**Parameters:**
- `query` (required): Text to search for
- `time_min` (optional): Start time in ISO format
- `time_max` (optional): End time in ISO format
- `max_results` (optional): Maximum results (default: 10)

### create_event
Create a new calendar event.

**Parameters:**
- `summary` (required): Event title
- `start_time` (required): Start time in ISO format
- `end_time` (required): End time in ISO format
- `description` (optional): Event description
- `location` (optional): Event location
- `attendees` (optional): Array of attendee email addresses
- `calendar_id` (optional): Calendar ID (default: 'primary')

**Example:**
```json
{
  "summary": "Team Meeting",
  "start_time": "2026-01-23T10:00:00-06:00",
  "end_time": "2026-01-23T11:00:00-06:00",
  "description": "Weekly sync",
  "location": "Conference Room A",
  "attendees": ["colleague@example.com"]
}
```

### list_calendars
List all calendars accessible to the user.

**No parameters required.**

## Time Format Notes

- All times should be in ISO 8601 format
- Include timezone offset for accuracy (e.g., `-06:00` for Central Time)
- UTC times should end with 'Z' (e.g., `2026-01-22T17:00:00Z`)

## Troubleshooting

### Authentication Issues
- Delete `~/.config/google-calendar-mcp/token.json` and re-authenticate
- Verify credentials.json is valid and in the correct location
- Check that Google Calendar API is enabled in Google Cloud Console

### Permission Errors
- Ensure the OAuth consent screen is configured
- Add test users if the app is in testing mode
- Verify the scopes include calendar access

## Security Notes

- Never commit `credentials.json` or `token.json` to version control
- The token file contains refresh tokens that provide ongoing access
- Regularly review OAuth app permissions in Google Account settings