GO
Productivity

Google Calendar Scheduling and Events for MCP Server

Manage Google Calendar on your MCP server to check schedules, find available times, and add or delete events seamlessly.

View on GitHub

Overview

This MCP (Model Context Protocol) server integration connects your MCP assistant to Google Calendar so the assistant can read schedules, search for free time, and create or remove events on behalf of users. It acts as a bridge between natural-language scheduling requests handled by an LLM and the Google Calendar API, making calendar operations accessible as structured tools within a conversation.

This is useful for building assistants that need to coordinate meetings, confirm availability, or keep calendar state in sync with user requests. The server includes endpoints that encapsulate common calendar flows (check conflicts, find availability windows, add/delete events) and handles OAuth authentication and calendar scopes needed to work with Google Calendar.

Features

  • Read events from a specified Google Calendar
  • Find available time slots based on duration and constraints
  • Create events with attendees, descriptions, and timezones
  • Delete events by event ID
  • Expose structured endpoints suitable for MCP/tooling integration
  • OAuth2-compatible configuration (support for refresh tokens or service accounts)
  • Timezone-aware RFC3339 timestamps

Installation / Configuration

Prerequisites:

  • Node.js 16+ (or the runtime used by the repository)
  • A Google Cloud project with Calendar API enabled
  • OAuth client credentials (or a service account with domain-wide delegation if required)

Example environment variables (.env):

# OAuth client-based approach
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REFRESH_TOKEN=your-refresh-token

# Alternatively for service account:
GOOGLE_SERVICE_ACCOUNT_JSON='{"type":"service_account",...}'

# Common settings
GOOGLE_CALENDAR_ID=primary
PORT=3000
MCP_API_KEY=your-mcp-api-key
TIMEZONE=America/Los_Angeles

Install and run (typical Node-based steps):

git clone https://github.com/v-3/google-calendar.git
cd google-calendar
npm install
npm run build    # if applicable
npm start

Run with Docker (example):

docker build -t mcp-google-calendar .
docker run -e GOOGLE_CLIENT_ID=... -e GOOGLE_CLIENT_SECRET=... -e GOOGLE_REFRESH_TOKEN=... -e GOOGLE_CALENDAR_ID=primary -p 3000:3000 mcp-google-calendar

If you use OAuth client credentials, obtain a refresh token via OAuth Playground or your web flow and supply it in GOOGLE_REFRESH_TOKEN. For service accounts, provide the JSON key in GOOGLE_SERVICE_ACCOUNT_JSON and set GOOGLE_CALENDAR_ID to the target calendar.

Available Tools / Resources

The server exposes RESTful endpoints intended to be used by MCP tools. Below is a summary table and sample request/response payloads.

EndpointMethodPurpose
/events/listPOSTList events in a time range
/events/find_availabilityPOSTFind free slots matching duration
/events/createPOSTCreate an event
/events/deletePOSTDelete an event by id

List events (request):

POST /events/list
{
  "timeMin": "2026-04-01T00:00:00-07:00",
  "timeMax": "2026-04-07T23:59:59-07:00",
  "maxResults": 50
}

List events (response excerpt):

{
  "items": [
    {
      "id": "abcd1234",
      "summary": "Team Sync",
      "start": {"dateTime": "2026-04-02T10:00:00-07:00"},
      "end": {"dateTime": "2026-04-02T11:00:00-07:00"}
    }
  ]
}

Find availability (request):

POST /events/find_availability
{
  "timeMin": "2026-04-05T08:00:00-07:00",
  "timeMax": "2026-04-09T18:00:00-07:00",
  "durationMinutes": 120,
  "workHours": {"start": "08:00", "end": "18:00"},
  "requiredAttendees": ["[email protected]"]
}

Create event (request):

POST /events/create
{
  "summary": "Project Review",
  "description": "Discuss Q2 roadmap",
  "start": {"dateTime": "2026-04-07T09:00:00-07:00"},
  "end":   {"dateTime": "2026-04-07T10:00:00-07:00"},
  "attendees": [{"email":"[email protected]"},{"email":"[email protected]"}],
  "reminders": {"useDefault": true}
}

Delete event (request):

POST /events/delete
{
  "eventId": "abcd1234"
}

Use Cases

  • Find a meeting slot: “Find a 90‑minute open slot for next week between 9am–5pm for Alice and me.” The assistant calls /events/find_availability with durationMinutes and requiredAttendees and returns candidate RFC3339 ranges.
  • Schedule a meeting: “Schedule a 30‑minute demo with [email protected] tomorrow at 2pm and include the meeting link.” The assistant maps the request to /events/create with start/end, attendees, and description.
  • Check conflicts before confirming: Before proposing a time to a user, the assistant lists events (/events/list) in the target window to detect overlaps and avoid double-booking.
  • Cancel an event by conversational reference: If the user says “Cancel my meeting called Project Review next Thursday,” the assistant finds the event by summary/date then calls /events/delete with the eventId.

Notes & Best Practices

  • Use RFC3339 timestamps (ISO 8601 with timezone) for start/end times.
  • Request calendar scopes:
    • readonly scenarios: https://www.googleapis.com/auth/calendar.readonly
    • create/delete events: https://www.googleapis.com/auth/calendar.events
  • Respect user privacy and store tokens securely (use secrets manager or vault).
  • When using service accounts with domain-wide delegation, set the impersonated user if accessing user calendars.

For implementation details and examples, see the repository on GitHub: https://github.com/v-3/google-calendar.

Tags:productivity