Google Calendar MCP Server

Package: @prmichaelsen/google-calendar-mcp Version: 2.0.0

A TypeScript-based Model Context Protocol (MCP) server for Google Calendar and Gmail integration using service account authentication with domain-wide delegation.

New in v2.0: Factory pattern support for multi-tenant deployments. Can be used as a standalone server or imported as a library for wrapper projects.

Note: This is a minimal implementation covering the most common use cases. The Google Calendar API has many more features (recurring events, calendar management, ACLs, etc.) that are not implemented here. This server focuses on basic event CRUD operations with reminders and attendee management.

Features

• ✅ Create calendar events with title, description, start/end times, location, and attendees
• ✅ Update existing calendar events
• ✅ List upcoming calendar events
• ✅ Custom event reminders (popup/email at any interval)
• ✅ Service account authentication with domain-wide delegation
• ✅ Automatic email notifications to attendees
• ✅ TypeScript implementation with full type safety

Prerequisites

• Node.js v18 or later
• Google Workspace account with admin access (for domain-wide delegation)
• Google Cloud Console project with Calendar API enabled
• Service account with Calendar API access and domain-wide delegation
• Service account JSON key file

Setup

1. Google Cloud Console Setup

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable the Google Calendar API:
   • Navigate to "APIs & Services" > "Library"
   • Search for "Google Calendar API"
   • Click "Enable"

2. Create Service Account

1. Go to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "Service Account"
3. Fill in service account details:
   • Name: calendar-mcp (or your choice)
   • ID: calendar-mcp@your-project.iam.gserviceaccount.com
4. Click "Create and Continue"
5. Grant appropriate roles (optional)
6. Click "Done"

3. Create Service Account Key

1. Click on the newly created service account
2. Go to the "Keys" tab
3. Click "Add Key" > "Create new key"
4. Select "JSON" and click "Create"
5. Save the downloaded JSON file as ~/calendar-mcp-server/service-account-key.json
6. Note the client_id from the JSON file - you'll need this for domain-wide delegation

4. Enable Domain-Wide Delegation (REQUIRED for attendee invitations)

This step is critical for sending calendar invitations to attendees.

1. In Google Admin Console:

   • Go to Google Admin Console
   • Navigate to: Security → Access and data control → API Controls
   • Click Manage Domain Wide Delegation
   • Click Add new

2. Configure delegation:

   • Client ID: Paste the client_id from your service account JSON key
   • OAuth Scopes: https://www.googleapis.com/auth/calendar
   • Click Authorize

3. Verify setup:

   • The service account should now appear in the Domain-Wide Delegation list
   • Status should show "Authorized"

Without domain-wide delegation: Events can be created but attendee invitations will fail with error:

Service accounts cannot invite attendees without Domain-Wide Delegation of Authority

5. Install Dependencies

cd ~/calendar-mcp-server
npm install

6. Build the Project

npx tsc

Configuration

Environment Variables

The server requires three environment variables:

• GOOGLE_APPLICATION_CREDENTIALS: Path to your service account JSON key file
• GOOGLE_CALENDAR_ID: Calendar ID to use (e.g., email address or "primary")
• GOOGLE_CALENDAR_SUBJECT: Email address to impersonate for domain-wide delegation

MCP Settings

Add to your MCP settings file (.vscode-server/data/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json):

{
  "mcpServers": {
    "@prmichaelsen/google-calendar-mcp": {
      "command": "node",
      "args": ["/path/to/calendar-mcp-server/build/index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/calendar-mcp-server/service-account-key.json",
        "GOOGLE_CALENDAR_ID": "your-email@your-domain.com",
        "GOOGLE_CALENDAR_SUBJECT": "your-email@your-domain.com"
      },
      "alwaysAllow": [
        "create_calendar_event",
        "list_calendar_events",
        "update_calendar_event",
        "send_email",
        "list_emails",
        "read_email"
      ]
    }
  }
}

Note: Replace paths and email addresses with your actual values.

Available Tools

create_calendar_event

Create a new calendar event with optional reminders and attendees.

Parameters:

• summary (required): Event title
• start_time (required): Start time in ISO 8601 format
• end_time (required): End time in ISO 8601 format
• description (optional): Event description
• location (optional): Event location
• attendees (optional): Array of attendee email addresses
• send_notifications (optional): Send email notifications (default: true)
• reminders (optional): Array of reminder objects with method ("email" or "popup") and minutes

Example:

{
  "summary": "Team Meeting",
  "description": "Weekly team sync",
  "start_time": "2024-12-25T10:00:00-08:00",
  "end_time": "2024-12-25T11:00:00-08:00",
  "location": "Conference Room A",
  "attendees": ["alice@example.com", "bob@example.com"],
  "reminders": [
    {
      "method": "popup",
      "minutes": 10
    },
    {
      "method": "email",
      "minutes": 1440
    }
  ]
}

Common Reminder Times:

• 10 minutes before: {method: "popup", minutes: 10}
• 1 hour before: {method: "popup", minutes: 60}
• 1 day before: {method: "email", minutes: 1440}
• 2 days before: {method: "email", minutes: 2880}
• 1 week before: {method: "email", minutes: 10080}

list_calendar_events

List upcoming calendar events with their IDs.

Parameters:

• max_results (optional): Maximum number of events to return (default: 10)
• time_min (optional): Lower bound for event start time in ISO 8601 format (default: now)
• time_max (optional): Upper bound for event start time in ISO 8601 format

Example:

{
  "max_results": 20,
  "time_min": "2024-12-01T00:00:00Z",
  "time_max": "2024-12-31T23:59:59Z"
}

update_calendar_event

Update an existing calendar event by its ID.

Parameters:

• event_id (required): Event ID to update
• summary (optional): New event title
• description (optional): New event description
• start_time (optional): New start time in ISO 8601 format
• end_time (optional): New end time in ISO 8601 format
• location (optional): New event location
• attendees (optional): New array of attendee email addresses
• send_notifications (optional): Send update notifications (default: true)
• reminders (optional): New reminder configuration

Example:

{
  "event_id": "abc123xyz",
  "summary": "Updated Team Meeting",
  "attendees": ["alice@example.com", "charlie@example.com"],
  "reminders": [
    {
      "method": "popup",
      "minutes": 30
    }
  ]
}

Using as a Library

This package can be used as a base for multi-tenant MCP servers:

import { createGoogleCalendarServer } from '@prmichaelsen/google-calendar-mcp/factory';

const server = createGoogleCalendarServer(
  'user@workspace.com',  // User to impersonate
  'user-123',            // User ID for tracking
  {
    serviceAccountKeyPath: '/path/to/key.json',
    calendarId: 'primary'
  }
);

// Connect to transport (stdio, SSE, etc.)
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const transport = new StdioServerTransport();
await server.connect(transport);

Factory Options

interface GoogleCalendarServerOptions {
  serviceAccountKeyPath: string;  // Required: Path to service account JSON key
  calendarId?: string;            // Optional: Calendar ID (defaults to "primary")
}

Multi-Tenant Integration

For multi-tenant deployments with Platform JWT authentication, see:

• Multi-Tenancy Design
• MCP Auth Integration Plan

The factory pattern enables wrapping this server with @prmichaelsen/mcp-auth for per-user authentication and authorization.

Tool Names

v2.0 Breaking Change: All tools now have a google_ prefix for multi-tenant compatibility:

• google_create_calendar_event (was create_calendar_event)
• google_list_calendar_events (was list_calendar_events)
• google_update_calendar_event (was update_calendar_event)
• google_send_email (was send_email)
• google_list_emails (was list_emails)
• google_read_email (was read_email)

Note: If you're using the standalone server (not as a library), update your MCP settings to use the new tool names.

Development

# Build
cd ~/calendar-mcp-server
npx tsc

# The compiled server will be at build/index.js

Troubleshooting

"Error: GOOGLE_CALENDAR_SUBJECT environment variable is required"

• Ensure GOOGLE_CALENDAR_SUBJECT is set in your MCP settings
• This should be the email address you want to impersonate (e.g., your Google Workspace email)

"Service accounts cannot invite attendees without Domain-Wide Delegation"

• Follow step 4 above to enable domain-wide delegation in Google Admin Console
• Ensure the OAuth scope https://www.googleapis.com/auth/calendar is authorized
• Verify the service account's client_id is correctly entered in Admin Console

"The user must be signed up for Google Calendar"

• The email specified in GOOGLE_CALENDAR_SUBJECT needs to visit calendar.google.com once to activate Google Calendar
• This is a one-time setup requirement

"Failed to create calendar event: Forbidden"

• Verify domain-wide delegation is properly configured
• Ensure Calendar API is enabled in Google Cloud Console
• Check that the service account has the calendar scope authorized

Architecture

Domain-Wide Delegation Flow:

1. Service account (calendar-mcp@your-project.iam.gserviceaccount.com) impersonates user
2. User email specified in GOOGLE_CALENDAR_SUBJECT environment variable
3. Calendar operations performed as that user
4. Attendee invitations sent from that user's calendar

Benefits:

• No OAuth2 browser flow required
• Automated calendar management
• Ability to send attendee invitations
• Suitable for server-side/bot applications

License

MIT