# Google Calendar MCP

## Google Calendar MCP

### What This Does

Enables Claude Code to list, search, create, and manage Google Calendar events.

### Source

* **GitHub:** <https://github.com/nspady/google-calendar-mcp>
* **Docker:** `ghcr.io/metorial/mcp-container--nspady--google-calendar-mcp--google-calendar-mcp`
* **Container Registry:** <https://github.com/metorial/mcp-containers>

### Prerequisites

* Docker Desktop installed
* @theentourageai.com Google account
* Google Cloud Project with Calendar API enabled

### Step 1: Create Local Config Folder

```bash
mkdir -p ~/.config/mcp/gcalendar
```

### Step 2: Get Credentials

#### Create Google Cloud OAuth Credentials

1. Go to <https://console.cloud.google.com>
2. Log in with your @theentourageai.com account
3. Create a new project or select existing one
4. Enable **Google Calendar API**:
   * Go to **APIs & Services → Library**
   * Search "Google Calendar API"
   * Click **Enable**

#### Create OAuth Client

1. Go to **APIs & Services → Credentials**
2. Click **Create Credentials → OAuth client ID**
3. Application type: **Desktop app**
4. Name: "Calendar MCP"
5. Click **Create**
6. Click **Download JSON**

#### Configure OAuth Consent Screen

1. Go to **APIs & Services → OAuth consent screen**
2. User type: **Internal** (for Workspace accounts)
3. Fill in:
   * App name: "Calendar MCP"
   * User support email: your @theentourageai.com email
   * Developer contact: your @theentourageai.com email
4. Add scopes:
   * `https://www.googleapis.com/auth/calendar`
   * `https://www.googleapis.com/auth/calendar.events`
   * `https://www.googleapis.com/auth/calendar.readonly`
5. Save

### Step 3: Save Credentials Locally

Move the downloaded OAuth JSON file:

```bash
mv ~/Downloads/client_secret_*.json ~/.config/mcp/gcalendar/credentials.json
```

### Step 4: Pull Docker Image

```bash
docker pull ghcr.io/metorial/mcp-container--nspady--google-calendar-mcp--google-calendar-mcp
```

### Step 5: First Run (Authentication)

Run with port exposed for OAuth callback:

```bash
docker run -it --rm \
  -v ~/.config/mcp/gcalendar:/app/config \
  -p 3000:3000 \
  ghcr.io/metorial/mcp-container--nspady--google-calendar-mcp--google-calendar-mcp
```

1. Open <http://localhost:3000/accounts> in browser
2. Click "Add Account"
3. Log in with your @theentourageai.com account
4. Grant permissions
5. Token will be saved to `~/.config/mcp/gcalendar/`

### Step 6: Add to Claude Code

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "gcalendar": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "${HOME}/.config/mcp/gcalendar:/app/config",
        "ghcr.io/metorial/mcp-container--nspady--google-calendar-mcp--google-calendar-mcp"
      ]
    }
  }
}
```

**Note:** If `${HOME}` doesn't expand, use absolute path:

```json
{
  "mcpServers": {
    "gcalendar": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/yourname/.config/mcp/gcalendar:/app/config",
        "ghcr.io/metorial/mcp-container--nspady--google-calendar-mcp--google-calendar-mcp"
      ]
    }
  }
}
```

### Step 7: Verify It Works

Restart Claude Code and test:

```
What's on my calendar for tomorrow?
```

Expected: List of calendar events for the next day.

### Available Tools

| Tool               | Description                       |
| ------------------ | --------------------------------- |
| `list-calendars`   | List all available calendars      |
| `list-events`      | List events from calendars        |
| `search-events`    | Search events by text query       |
| `get-event`        | Get specific event details        |
| `create-event`     | Create a new calendar event       |
| `update-event`     | Update an existing event          |
| `delete-event`     | Delete a calendar event           |
| `get-freebusy`     | Check availability                |
| `get-current-time` | Get current time                  |
| `respond-to-event` | Accept/decline/tentative response |
| `list-colors`      | List available event colors       |

### Multi-Account Setup

This MCP supports multiple Google accounts:

1. Run container with port 3000 exposed
2. Visit `http://localhost:3000/accounts`
3. Click "Add Account" for each account
4. Give each account a nickname (e.g., "work", "personal")

Query multiple accounts:

```
List events from my work and personal calendars for tomorrow
```

### Troubleshooting

| Issue                | Solution                                         |
| -------------------- | ------------------------------------------------ |
| "Access blocked"     | Add your email as test user in OAuth consent     |
| Token expired        | Re-authenticate via /accounts endpoint           |
| "Calendar not found" | Use `list-calendars` to find correct calendar ID |
| No events returned   | Verify date range is correct                     |
| Permission denied    | Check OAuth scopes include calendar access       |
| Port 3000 in use     | Stop other services or use different port        |