npm package: @striderlabs/mcp-gcal
Description: MCP server connector for Google Calendar
Author: Strider Labs
Latest version: 0.1.1

# @striderlabs/mcp-gcal

Google Calendar MCP server connector for [Strider Labs](https://striderlabs.io). Connects Claude (or any MCP client) directly to Google Calendar via the native Google Calendar REST API and OAuth 2.0.

## Setup

### 1. Google Cloud Console

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a project (or select an existing one)
3. Enable the **Google Calendar API**
4. Create OAuth 2.0 credentials (Desktop app or Web app)
5. Note your **Client ID** and **Client Secret**

### 2. Environment variables

```bash
export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-client-secret"
# Optional - defaults to http://localhost:3456/callback
export GOOGLE_REDIRECT_URI="http://localhost:3456/callback"
```

### 3. Claude Desktop config

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gcal": {
      "command": "npx",
      "args": ["-y", "@striderlabs/mcp-gcal"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

### 4. Authenticate

Use the `auth` tool to get an OAuth URL, open it in your browser, then use `auth_callback` with the code from the redirect URL.

---

## Tools

### Authentication

| Tool | Description |
|------|-------------|
| `status` | Check OAuth token validity and logged-in account |
| `auth` | Start OAuth flow — returns a URL to open in browser |
| `auth_callback` | Complete OAuth with the `code` from the redirect URL |
| `logout` | Revoke and clear stored tokens |

### Calendars

| Tool | Description |
|------|-------------|
| `list_calendars` | List all accessible calendars |
| `get_calendar` | Get details for a specific calendar by ID |

### Events

| Tool | Description |
|------|-------------|
| `list_events` | List events with optional filters (date range, text search, max results) |
| `get_event` | Get full details of a specific event |
| `create_event` | Create a new event (supports attendees, recurrence, reminders, all-day) |
| `update_event` | Update fields on an existing event |
| `delete_event` | Delete an event |
| `quick_add` | Natural language event creation, e.g. "Lunch with Bob tomorrow at noon" |
| `find_free_time` | Find free time slots across one or more calendars |

---

## Tool details

### `list_events`

```
calendar_id      string   Calendar ID (default: "primary")
time_min         string   ISO 8601 start of range
time_max         string   ISO 8601 end of range
query            string   Free-text search
max_results      number   Max events to return (default: 10)
single_events    boolean  Expand recurring events (default: true)
order_by         string   "startTime" or "updated"
```

### `create_event`

```
summary *        string   Event title
start *          string   ISO 8601 datetime or YYYY-MM-DD for all-day
end *            string   ISO 8601 datetime or YYYY-MM-DD for all-day
calendar_id      string   Calendar ID (default: "primary")
description      string   Event body
location         string   Location string
timezone         string   e.g. "America/Los_Angeles"
attendees        string[] List of email addresses
recurrence       string[] RRULE strings
reminders        object   { use_default, overrides: [{method, minutes}] }
```

### `find_free_time`

```
time_min *       string   ISO 8601 start of search range
time_max *       string   ISO 8601 end of search range
calendar_ids     string[] Calendar IDs to check (default: ["primary"])
duration_minutes number   Minimum free slot length in minutes (default: 30)
timezone         string   Timezone for results (default: "UTC")
```

---

## Token storage

Tokens are stored at `~/.striderlabs/gcal/token.json`. They are refreshed automatically before expiry.

---

## License

MIT — Strider Labs