@franciscpd/calendar-mcp-server

A Model Context Protocol (MCP) server for Google Calendar. Read, search, create, update, and delete calendar events, check availability, and list calendars — powered by 3 environment variables.

Quick Start

npx -y @franciscpd/calendar-mcp-server

Set these environment variables:

| Variable | Description | |----------|-------------| | GOOGLE_CALENDAR_CLIENT_ID | OAuth2 client ID from Google Cloud Console | | GOOGLE_CALENDAR_CLIENT_SECRET | OAuth2 client secret | | GOOGLE_CALENDAR_REFRESH_TOKEN | OAuth2 refresh token (see Setup Guide) |

Setup Guide

1. Create a Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project (or select an existing one)
3. Note your project name for the next steps

2. Enable the Google Calendar API

1. Navigate to APIs & Services → Library
2. Search for "Google Calendar API"
3. Click Enable

3. Create OAuth2 Credentials

1. Navigate to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. If prompted, configure the OAuth consent screen:
   • User type: External (or Internal for Workspace)
   • Add the scopes:
     • https://www.googleapis.com/auth/calendar.readonly
     • https://www.googleapis.com/auth/calendar.events
   • Add your email as a test user
4. Application type: Web application
5. Add https://developers.google.com/oauthplayground as an authorized redirect URI
6. Save your Client ID and Client Secret

4. Get a Refresh Token

1. Go to Google OAuth2 Playground
2. Click the gear icon (top right) and check Use your own OAuth credentials
3. Enter your Client ID and Client Secret
4. In the left panel, find Google Calendar API v3 and select:
   • https://www.googleapis.com/auth/calendar.readonly
   • https://www.googleapis.com/auth/calendar.events
5. Click Authorize APIs and grant access
6. Click Exchange authorization code for tokens
7. Copy the Refresh token

Important: OAuth Consent Screen

If your OAuth consent screen is in Testing mode, refresh tokens expire after 7 days. To avoid this:

• Option A: Publish your app (set status to "In production" in the OAuth consent screen settings). No Google review is needed for apps used only by you.
• Option B: Add specific Google accounts as test users in the OAuth consent screen settings. Tokens for test users still expire after 7 days, but you can re-authorize.

For personal use, Option A is recommended — publish the app so tokens don't expire.

See Google's OAuth consent screen documentation for details.

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["-y", "@franciscpd/calendar-mcp-server"],
      "env": {
        "GOOGLE_CALENDAR_CLIENT_ID": "your-client-id",
        "GOOGLE_CALENDAR_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_CALENDAR_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["-y", "@franciscpd/calendar-mcp-server"],
      "env": {
        "GOOGLE_CALENDAR_CLIENT_ID": "your-client-id",
        "GOOGLE_CALENDAR_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_CALENDAR_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Generic MCP Client

GOOGLE_CALENDAR_CLIENT_ID=your-client-id \
GOOGLE_CALENDAR_CLIENT_SECRET=your-client-secret \
GOOGLE_CALENDAR_REFRESH_TOKEN=your-refresh-token \
npx -y @franciscpd/calendar-mcp-server

The server communicates over stdio using the MCP protocol.

Tools

| Tool | Description | |------|-------------| | calendar_list_calendars | List all calendars with id, name, timezone, color, and access role | | calendar_list_events | List events from a calendar within a date range (default: next 7 days) | | calendar_get_event | Get full event details including attendees, recurrence, and reminders | | calendar_search_events | Search events by text across summaries, descriptions, and locations | | calendar_get_freebusy | Check free/busy availability for one or more calendars | | calendar_create_event | Create a new calendar event (timed or all-day) | | calendar_update_event | Update an existing event (partial update — only specified fields change) | | calendar_delete_event | Delete a calendar event |

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Start the server
npm start

License

MIT