# mcp-google-gcal

An [MCP](https://modelcontextprotocol.io/) server for Google Calendar. Lets AI assistants manage events, calendars, sharing, and scheduling with full read/write access across multiple Google accounts. Supports natural language event creation, recurring events, Google Meet conferencing, free/busy queries, and ACL management.

## Tools

### Events

| Tool | Description |
|------|-------------|
| `gcal_list_events` | List events with time range, search, pagination, and event type filtering |
| `gcal_get_event` | Get full event details by ID |
| `gcal_create_event` | Create event with attendees, recurrence, Google Meet, attachments, and more |
| `gcal_update_event` | Update event fields using patch semantics |
| `gcal_delete_event` | Delete event with notification control |
| `gcal_quick_add` | Create event from natural language text |
| `gcal_move_event` | Move an event from one calendar to another |
| `gcal_list_instances` | List individual occurrences of a recurring event |
| `gcal_import_event` | Import event from external system preserving iCalUID |

### Calendars

| Tool | Description |
|------|-------------|
| `gcal_list_calendars` | List all calendars on the user's calendar list |
| `gcal_get_calendar` | Get calendar metadata (summary, description, timezone) |
| `gcal_create_calendar` | Create a new secondary calendar |
| `gcal_update_calendar` | Edit calendar metadata using patch semantics |
| `gcal_delete_calendar` | Delete a secondary calendar |
| `gcal_clear_calendar` | Clear all events from the primary calendar (irreversible) |

### Calendar List (User Preferences)

| Tool | Description |
|------|-------------|
| `gcal_get_calendar_list_entry` | Get a calendar's list-level settings (color, reminders, notifications) |
| `gcal_subscribe_calendar` | Add an existing calendar to the user's calendar list |
| `gcal_update_calendar_list_entry` | Update color, reminders, or notification preferences |
| `gcal_unsubscribe_calendar` | Remove a calendar from the user's list (does not delete it) |

### Access Control (Sharing)

| Tool | Description |
|------|-------------|
| `gcal_list_acl` | List sharing permissions on a calendar |
| `gcal_add_acl` | Share a calendar with a user, group, or domain |
| `gcal_update_acl` | Change the sharing role for an existing rule |
| `gcal_remove_acl` | Revoke a sharing rule |

### Utilities

| Tool | Description |
|------|-------------|
| `gcal_list_settings` | List user calendar settings (timezone, locale, format preferences) |
| `gcal_get_colors` | Get color definitions for calendars and events |
| `gcal_freebusy` | Query free/busy information for calendars and groups |

## Output Formats

All read and list tools support an `outputFormat` parameter:

| Format | Description | Use Case |
|--------|-------------|----------|
| `json` | Pretty-printed JSON (default) | Machine consumption, API pipelines |
| `yaml` | YAML serialization | Human-readable structured data |
| `text` | Compact aligned tables and key-value pairs | Quick scanning, token-efficient LLM context |

## Prerequisites

- Node.js 18+
- A Google Cloud project with the **Google Calendar API** enabled
- OAuth2 desktop application credentials

## Setup

1. Create or use an existing project in the [Google Cloud Console](https://console.cloud.google.com/) and enable the Google Calendar API
2. Create OAuth2 credentials (Application type: Desktop app) and download the JSON file
3. Save the credentials file:

```bash
mkdir -p ~/.config/mcp-google-gcal
cp ~/Downloads/client_secret_*.json ~/.config/mcp-google-gcal/credentials.json
```

4. Run the one-time authorization flow:

```bash
npx mcp-google-gcal --auth primary
```

This prints a URL for Google consent. After granting access, paste the authorization code back into the terminal.

### Multi-Account Setup

Add additional accounts with unique labels:

```bash
npx mcp-google-gcal --auth work
npx mcp-google-gcal --auth personal
```

Pass the `account` parameter to any tool to specify which account to use.

### MCP Client Configuration

#### Claude Code
```bash
claude mcp add -s user google-gcal -- npx -y mcp-google-gcal
```

#### VS Code / Cursor
```json
{
  "mcpServers": {
    "google-gcal": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-gcal"]
    }
  }
}
```

#### Gemini CLI
```json
{
  "mcpServers": {
    "google-gcal": {
      "command": "npx",
      "args": ["-y", "mcp-google-gcal"]
    }
  }
}
```

## License

MIT