google-calendar-workspace-mcp-server 0.0.1

package/README.md

@@ -0,0 +1,262 @@
+# Google Calendar Workspace MCP Server
+
+An MCP (Model Context Protocol) server for Google Calendar integration using service account authentication with domain-wide delegation. This server enables AI assistants to interact with Google Calendar to list events, create events, manage calendars, and query availability.
+
+## Features
+
+- **List Events**: View calendar events within a specified time range with filtering
+- **Get Event Details**: Retrieve complete information about specific events
+- **Create Events**: Create new calendar events with attendees, location, and descriptions
+- **List Calendars**: Discover available calendars
+- **Query Free/Busy**: Check availability and find busy time slots
+
+## Prerequisites
+
+1. **Google Cloud Project** with Calendar API enabled
+2. **Service Account** with domain-wide delegation
+3. **Google Workspace Admin** access to grant calendar permissions
+
+## Setup
+
+### 1. Create a Google Cloud Service Account
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create or select a project
+3. Enable the Google Calendar API:
+   - Navigate to "APIs & Services" > "Library"
+   - Search for "Google Calendar API"
+   - Click "Enable"
+4. Create a service account:
+   - Navigate to "IAM & Admin" > "Service Accounts"
+   - Click "Create Service Account"
+   - Provide a name and description
+   - Click "Create and Continue"
+   - Skip granting roles (not needed for domain-wide delegation)
+   - Click "Done"
+5. Create a key for the service account:
+   - Click on the created service account
+   - Go to "Keys" tab
+   - Click "Add Key" > "Create new key"
+   - Select "JSON" format
+   - Download the key file
+6. Note the service account's **Client ID** (found in the service account details)
+
+### 2. Enable Domain-Wide Delegation
+
+1. In the service account details, click "Show domain-wide delegation"
+2. Check "Enable Google Workspace Domain-wide Delegation"
+3. Save the changes
+4. Note the **Client ID** (you'll need this for the next step)
+
+### 3. Grant Calendar Permissions in Google Workspace Admin
+
+1. Go to [Google Workspace Admin Console](https://admin.google.com/)
+2. Navigate to "Security" > "Access and data control" > "API Controls"
+3. Click "Manage Domain Wide Delegation"
+4. Click "Add new"
+5. Enter the service account's **Client ID**
+6. In the "OAuth Scopes" field, add:
+   ```
+   https://www.googleapis.com/auth/calendar
+   ```
+7. Click "Authorize"
+
+### 4. Configure Environment Variables
+
+Extract the following from your downloaded JSON key file:
+
+- `client_email`: The service account email
+- `private_key`: The private key (including `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----`)
+
+Set these environment variables:
+
+```bash
+export GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL="your-service-account@your-project.iam.gserviceaccount.com"
+export GCAL_SERVICE_ACCOUNT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour private key content\n-----END PRIVATE KEY-----"
+export GCAL_IMPERSONATE_EMAIL="user@yourdomain.com"
+```
+
+**Note**: `GCAL_IMPERSONATE_EMAIL` should be the email address of the user whose calendar you want to access.
+
+## Installation
+
+### Using NPX (Recommended)
+
+```bash
+npx google-calendar-workspace-mcp-server
+```
+
+### Using NPM
+
+```bash
+npm install -g google-calendar-workspace-mcp-server
+google-calendar-workspace-mcp-server
+```
+
+## Usage with Claude Desktop
+
+Add this configuration to your Claude Desktop config file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "google-calendar": {
+      "command": "npx",
+      "args": ["google-calendar-workspace-mcp-server"],
+      "env": {
+        "GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL": "your-service-account@your-project.iam.gserviceaccount.com",
+        "GCAL_SERVICE_ACCOUNT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nYour private key\n-----END PRIVATE KEY-----",
+        "GCAL_IMPERSONATE_EMAIL": "user@yourdomain.com"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### gcal_list_events
+
+Lists events from a calendar within an optional time range.
+
+**Parameters:**
+
+- `calendar_id` (optional): Calendar ID (default: "primary")
+- `time_min` (optional): Start time in RFC3339 format
+- `time_max` (optional): End time in RFC3339 format
+- `max_results` (optional): Maximum events to return (default: 10, max: 250)
+- `query` (optional): Free text search query
+- `single_events` (optional): Expand recurring events (default: true)
+- `order_by` (optional): "startTime" or "updated"
+
+**Example:**
+
+```
+List my events for the next week
+```
+
+### gcal_get_event
+
+Retrieves detailed information about a specific event.
+
+**Parameters:**
+
+- `event_id` (required): The event ID
+- `calendar_id` (optional): Calendar ID (default: "primary")
+
+**Example:**
+
+```
+Get details for event ID abc123
+```
+
+### gcal_create_event
+
+Creates a new calendar event.
+
+**Parameters:**
+
+- `summary` (required): Event title
+- `start_datetime` OR `start_date` (required): Event start time
+- `end_datetime` OR `end_date` (required): Event end time
+- `description` (optional): Event description
+- `location` (optional): Event location
+- `attendees` (optional): Array of email addresses
+- `calendar_id` (optional): Calendar ID (default: "primary")
+
+**Example:**
+
+```
+Create a meeting tomorrow at 2pm for 1 hour titled "Team Sync"
+```
+
+### gcal_list_calendars
+
+Lists all calendars available to the authenticated user.
+
+**Parameters:**
+
+- `max_results` (optional): Maximum calendars to return (default: 50, max: 250)
+
+**Example:**
+
+```
+Show all my calendars
+```
+
+### gcal_query_freebusy
+
+Queries availability information for calendars.
+
+**Parameters:**
+
+- `time_min` (required): Start time in RFC3339 format
+- `time_max` (required): End time in RFC3339 format
+- `calendar_ids` (required): Array of calendar IDs to check
+- `timezone` (optional): Time zone for the query
+
+**Example:**
+
+```
+Check if I'm free tomorrow between 2pm and 4pm
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm run install-all
+
+# Build the project
+npm run build
+
+# Run in development mode
+npm run dev
+
+# Run tests
+npm test
+
+# Run integration tests
+npm run test:integration
+
+# Run all tests
+npm run test:all
+```
+
+## Security Considerations
+
+- **Private Key Security**: Never commit your service account private key to version control
+- **Least Privilege**: Only grant the minimum required OAuth scopes
+- **Key Rotation**: Regularly rotate service account keys
+- **Access Logging**: Monitor service account usage in Google Cloud Console
+
+## Troubleshooting
+
+### Authentication Failed
+
+- Verify service account credentials are correct
+- Ensure domain-wide delegation is enabled
+- Check that the correct OAuth scope is authorized in Admin Console
+- Verify the impersonate email address is correct
+
+### Permission Denied
+
+- Ensure the calendar scope (`https://www.googleapis.com/auth/calendar`) is granted in Google Workspace Admin Console
+- Verify the impersonated user has access to the calendar
+
+### Calendar Not Found
+
+- Check that the calendar ID is correct
+- Verify the impersonated user has access to the calendar
+- Use `gcal_list_calendars` to discover available calendar IDs
+
+## License
+
+MIT
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.integration-with-mock.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Integration test entry point with mock Google Calendar client
+ * Used by TestMCPClient for integration tests
+ */
+export {};

package/build/index.integration-with-mock.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * Integration test entry point with mock Google Calendar client
+ * Used by TestMCPClient for integration tests
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMCPServer } from '../shared/index.js';
+import { logServerStart } from '../shared/logging.js';
+/**
+ * Mock Google Calendar client for integration tests
+ */
+class MockCalendarClient {
+    async listEvents(calendarId, options) {
+        const mockEvents = [
+            {
+                id: 'event1',
+                summary: 'Team Standup',
+                description: 'Daily team sync',
+                start: {
+                    dateTime: '2024-01-15T10:00:00-05:00',
+                    timeZone: 'America/New_York',
+                },
+                end: {
+                    dateTime: '2024-01-15T10:30:00-05:00',
+                    timeZone: 'America/New_York',
+                },
+                status: 'confirmed',
+                htmlLink: 'https://calendar.google.com/event?eid=event1',
+                attendees: [
+                    {
+                        email: 'user1@example.com',
+                        responseStatus: 'accepted',
+                    },
+                    {
+                        email: 'user2@example.com',
+                        responseStatus: 'tentative',
+                    },
+                ],
+            },
+            {
+                id: 'event2',
+                summary: 'All Day Event',
+                start: {
+                    date: '2024-01-16',
+                },
+                end: {
+                    date: '2024-01-17',
+                },
+                status: 'confirmed',
+                htmlLink: 'https://calendar.google.com/event?eid=event2',
+            },
+        ];
+        const filteredEvents = options?.q
+            ? mockEvents.filter((e) => e.summary?.toLowerCase().includes(options.q.toLowerCase()))
+            : mockEvents;
+        return {
+            kind: 'calendar#events',
+            etag: 'mock-etag',
+            summary: calendarId === 'primary' ? 'Primary Calendar' : calendarId,
+            updated: new Date().toISOString(),
+            timeZone: 'America/New_York',
+            accessRole: 'owner',
+            items: filteredEvents.slice(0, options?.maxResults || 10),
+        };
+    }
+    async getEvent(calendarId, eventId) {
+        if (eventId === 'event1') {
+            return {
+                id: 'event1',
+                summary: 'Team Standup',
+                description: 'Daily team sync',
+                location: 'Conference Room A',
+                start: {
+                    dateTime: '2024-01-15T10:00:00-05:00',
+                    timeZone: 'America/New_York',
+                },
+                end: {
+                    dateTime: '2024-01-15T10:30:00-05:00',
+                    timeZone: 'America/New_York',
+                },
+                status: 'confirmed',
+                htmlLink: 'https://calendar.google.com/event?eid=event1',
+                created: '2024-01-01T00:00:00Z',
+                updated: '2024-01-01T00:00:00Z',
+                creator: {
+                    email: 'creator@example.com',
+                    displayName: 'Event Creator',
+                },
+                organizer: {
+                    email: 'organizer@example.com',
+                    displayName: 'Event Organizer',
+                },
+                attendees: [
+                    {
+                        email: 'user1@example.com',
+                        displayName: 'User One',
+                        responseStatus: 'accepted',
+                    },
+                    {
+                        email: 'user2@example.com',
+                        displayName: 'User Two',
+                        responseStatus: 'tentative',
+                    },
+                ],
+                reminders: {
+                    useDefault: false,
+                    overrides: [
+                        {
+                            method: 'email',
+                            minutes: 30,
+                        },
+                    ],
+                },
+            };
+        }
+        throw new Error(`Event not found: ${eventId}`);
+    }
+    async createEvent(calendarId, event) {
+        return {
+            id: 'new-event-id',
+            summary: event.summary || 'New Event',
+            description: event.description,
+            location: event.location,
+            start: event.start || { dateTime: '2024-01-20T10:00:00-05:00' },
+            end: event.end || { dateTime: '2024-01-20T11:00:00-05:00' },
+            status: 'confirmed',
+            htmlLink: 'https://calendar.google.com/event?eid=new-event-id',
+            created: new Date().toISOString(),
+            updated: new Date().toISOString(),
+            attendees: event.attendees,
+        };
+    }
+    async listCalendars(_options) {
+        return {
+            kind: 'calendar#calendarList',
+            etag: 'mock-etag',
+            items: [
+                {
+                    kind: 'calendar#calendarListEntry',
+                    etag: 'mock-etag-1',
+                    id: 'primary',
+                    summary: 'Primary Calendar',
+                    timeZone: 'America/New_York',
+                    accessRole: 'owner',
+                    primary: true,
+                    selected: true,
+                    backgroundColor: '#9fc6e7',
+                    foregroundColor: '#000000',
+                },
+                {
+                    kind: 'calendar#calendarListEntry',
+                    etag: 'mock-etag-2',
+                    id: 'work@example.com',
+                    summary: 'Work Calendar',
+                    description: 'Work-related events',
+                    timeZone: 'America/New_York',
+                    accessRole: 'writer',
+                    selected: true,
+                    backgroundColor: '#f83a22',
+                    foregroundColor: '#000000',
+                },
+            ],
+        };
+    }
+    async queryFreebusy(request) {
+        return {
+            kind: 'calendar#freeBusy',
+            timeMin: request.timeMin,
+            timeMax: request.timeMax,
+            calendars: {
+                primary: {
+                    busy: [
+                        {
+                            start: '2024-01-15T10:00:00-05:00',
+                            end: '2024-01-15T10:30:00-05:00',
+                        },
+                        {
+                            start: '2024-01-15T14:00:00-05:00',
+                            end: '2024-01-15T15:00:00-05:00',
+                        },
+                    ],
+                },
+            },
+        };
+    }
+}
+async function main() {
+    const { server, registerHandlers } = createMCPServer();
+    // Register handlers with mock client factory
+    await registerHandlers(server, () => new MockCalendarClient());
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logServerStart('google-calendar-workspace-mcp-server-integration-mock');
+}
+main();

package/build/index.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMCPServer } from '../shared/index.js';
+import { logServerStart, logError } from '../shared/logging.js';
+async function main() {
+    // Validate required environment variables
+    const requiredVars = [
+        'GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL',
+        'GCAL_SERVICE_ACCOUNT_PRIVATE_KEY',
+        'GCAL_IMPERSONATE_EMAIL',
+    ];
+    const missing = requiredVars.filter((varName) => !process.env[varName]);
+    if (missing.length > 0) {
+        console.error('Error: Missing required environment variables:');
+        for (const varName of missing) {
+            console.error(`  - ${varName}`);
+        }
+        console.error('\nPlease set these environment variables to use the Google Calendar MCP server.');
+        console.error('See README.md for setup instructions.');
+        process.exit(1);
+    }
+    try {
+        const { server, registerHandlers } = createMCPServer();
+        // Register handlers with default client factory
+        await registerHandlers(server);
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        logServerStart('google-calendar-workspace-mcp-server');
+    }
+    catch (error) {
+        logError('server-startup', error);
+        process.exit(1);
+    }
+}
+main();

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "google-calendar-workspace-mcp-server",
+  "version": "0.0.1",
+  "description": "MCP server for Google Calendar integration with service account support",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "google-calendar-workspace-mcp-server": "./build/index.js"
+  },
+  "files": [
+    "build/**/*.js",
+    "build/**/*.d.ts",
+    "shared/**/*.js",
+    "shared/**/*.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && npm run build:integration",
+    "build:integration": "tsc -p tsconfig.integration.json",
+    "start": "node build/index.js",
+    "dev": "tsx src/index.ts",
+    "predev": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prebuild": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prepublishOnly": "node prepare-publish.js && node ../scripts/prepare-npm-readme.js",
+    "lint": "eslint . --ext .ts,.tsx",
+    "lint:fix": "eslint . --ext .ts,.tsx --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "stage-publish": "npm version"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.19.1",
+    "google-auth-library": "^10.5.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.6",
+    "tsx": "^4.19.4",
+    "typescript": "^5.7.3"
+  },
+  "keywords": [
+    "mcp",
+    "google-calendar",
+    "calendar",
+    "model-context-protocol"
+  ],
+  "author": "PulseMCP",
+  "license": "MIT"
+}

package/shared/calendar-client/lib/api-errors.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Structured error handling for Google Calendar API errors
+ */
+export declare function handleApiError(status: number, operation: string, resourceId?: string): never;

package/shared/calendar-client/lib/api-errors.js

@@ -0,0 +1,25 @@
+/**
+ * Structured error handling for Google Calendar API errors
+ */
+export function handleApiError(status, operation, resourceId) {
+    if (status === 401) {
+        throw new Error('Service account authentication failed. Verify the credentials and domain-wide delegation.');
+    }
+    if (status === 403) {
+        throw new Error('Permission denied. Ensure calendar scope is granted in Google Workspace Admin Console.');
+    }
+    if (status === 404) {
+        const resource = resourceId ? `: ${resourceId}` : '';
+        throw new Error(`Calendar resource not found${resource}`);
+    }
+    if (status === 429) {
+        throw new Error('Google Calendar API rate limit exceeded. Please try again later.');
+    }
+    if (status === 400) {
+        throw new Error(`Bad request while ${operation}. Check the request parameters.`);
+    }
+    if (status === 410) {
+        throw new Error('Calendar sync token expired. The sync state is no longer valid.');
+    }
+    throw new Error(`Google Calendar API error while ${operation}: HTTP ${status}`);
+}

package/shared/calendar-client/lib/create-event.d.ts

@@ -0,0 +1,2 @@
+import type { CalendarEvent } from '../../types.js';
+export declare function createEvent(baseUrl: string, headers: Record<string, string>, calendarId: string, event: Partial<CalendarEvent>): Promise<CalendarEvent>;

package/shared/calendar-client/lib/create-event.js

@@ -0,0 +1,13 @@
+import { handleApiError } from './api-errors.js';
+export async function createEvent(baseUrl, headers, calendarId, event) {
+    const url = `${baseUrl}/calendars/${encodeURIComponent(calendarId)}/events`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(event),
+    });
+    if (!response.ok) {
+        handleApiError(response.status, 'creating calendar event', calendarId);
+    }
+    return (await response.json());
+}

package/shared/calendar-client/lib/get-event.d.ts

@@ -0,0 +1,2 @@
+import type { CalendarEvent } from '../../types.js';
+export declare function getEvent(baseUrl: string, headers: Record<string, string>, calendarId: string, eventId: string): Promise<CalendarEvent>;

package/shared/calendar-client/lib/get-event.js

@@ -0,0 +1,9 @@
+import { handleApiError } from './api-errors.js';
+export async function getEvent(baseUrl, headers, calendarId, eventId) {
+    const url = `${baseUrl}/calendars/${encodeURIComponent(calendarId)}/events/${encodeURIComponent(eventId)}`;
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+        handleApiError(response.status, 'getting calendar event', eventId);
+    }
+    return (await response.json());
+}

package/shared/calendar-client/lib/list-calendars.d.ts

@@ -0,0 +1,5 @@
+import type { CalendarList } from '../../types.js';
+export declare function listCalendars(baseUrl: string, headers: Record<string, string>, options?: {
+    maxResults?: number;
+    pageToken?: string;
+}): Promise<CalendarList>;

package/shared/calendar-client/lib/list-calendars.js

@@ -0,0 +1,14 @@
+import { handleApiError } from './api-errors.js';
+export async function listCalendars(baseUrl, headers, options) {
+    const params = new URLSearchParams();
+    if (options?.maxResults)
+        params.append('maxResults', options.maxResults.toString());
+    if (options?.pageToken)
+        params.append('pageToken', options.pageToken);
+    const url = `${baseUrl}/users/me/calendarList?${params}`;
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+        handleApiError(response.status, 'listing calendars');
+    }
+    return (await response.json());
+}

package/shared/calendar-client/lib/list-events.d.ts

@@ -0,0 +1,10 @@
+import type { CalendarEventList } from '../../types.js';
+export declare function listEvents(baseUrl: string, headers: Record<string, string>, calendarId: string, options?: {
+    timeMin?: string;
+    timeMax?: string;
+    maxResults?: number;
+    pageToken?: string;
+    q?: string;
+    singleEvents?: boolean;
+    orderBy?: string;
+}): Promise<CalendarEventList>;

package/shared/calendar-client/lib/list-events.js

@@ -0,0 +1,24 @@
+import { handleApiError } from './api-errors.js';
+export async function listEvents(baseUrl, headers, calendarId, options) {
+    const params = new URLSearchParams();
+    if (options?.timeMin)
+        params.append('timeMin', options.timeMin);
+    if (options?.timeMax)
+        params.append('timeMax', options.timeMax);
+    if (options?.maxResults)
+        params.append('maxResults', options.maxResults.toString());
+    if (options?.pageToken)
+        params.append('pageToken', options.pageToken);
+    if (options?.q)
+        params.append('q', options.q);
+    if (options?.singleEvents !== undefined)
+        params.append('singleEvents', options.singleEvents.toString());
+    if (options?.orderBy)
+        params.append('orderBy', options.orderBy);
+    const url = `${baseUrl}/calendars/${encodeURIComponent(calendarId)}/events?${params}`;
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+        handleApiError(response.status, 'listing calendar events', calendarId);
+    }
+    return (await response.json());
+}

package/shared/calendar-client/lib/query-freebusy.d.ts

@@ -0,0 +1,2 @@
+import type { FreeBusyRequest, FreeBusyResponse } from '../../types.js';
+export declare function queryFreebusy(baseUrl: string, headers: Record<string, string>, request: FreeBusyRequest): Promise<FreeBusyResponse>;