### Google Calendar MCP Setup

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/00-START-HERE.md

Minimal setup involves setting the OAuth credentials path, running the authentication flow, and starting the server. Ensure the path to your GCP OAuth keys is correctly exported.

```bash
# 1. Set OAuth credentials path
export GOOGLE_OAUTH_CREDENTIALS="/path/to/gcp-oauth.keys.json"

# 2. Run auth flow
npx @cocal/google-calendar-mcp auth

# 3. Start server
npx @cocal/google-calendar-mcp
```

--------------------------------

### Install Dependencies

Source: https://github.com/nspady/google-calendar-mcp/blob/main/CLAUDE.md

Installs all necessary project dependencies.

```bash
npm install
```

--------------------------------

### Quick Setup for Development Tests

Source: https://github.com/nspady/google-calendar-mcp/blob/main/CLAUDE.md

Minimal setup commands for running direct integration tests during development. This includes setting credentials, test calendar, and authentication.

```bash
# Minimal setup for development (direct integration tests only):
export GOOGLE_OAUTH_CREDENTIALS=./gcp-oauth.keys.json
export TEST_CALENDAR_ID=primary
npm run dev auth:test
npm run dev test:integration:direct
```

--------------------------------

### Example .env File Configuration

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/testing.md

This example shows how to configure required and optional environment variables in a .env file for integration tests. Ensure sensitive keys are kept secure.

```env
# Required for all integration tests
GOOGLE_OAUTH_CREDENTIALS=./gcp-oauth.keys.json
TEST_CALENDAR_ID=test-calendar@gmail.com

# Required for LLM integration tests
CLAUDE_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-...

# Required for attendee tests
INVITEE_1=test1@example.com
INVITEE_2=test2@example.com

# Optional configurations
GOOGLE_ACCOUNT_MODE=test
DEBUG_LLM_INTERACTIONS=false
ANTHROPIC_MODEL=claude-3-5-haiku-20241022
OPENAI_MODEL=gpt-4o-mini
```

--------------------------------

### Start HTTP Server

Source: https://github.com/nspady/google-calendar-mcp/blob/main/CLAUDE.md

Starts the server with an HTTP transport, accessible on localhost:3000.

```bash
npm run dev http
```

--------------------------------

### Clone and Install Project Dependencies

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/development.md

Clone the repository, navigate into the project directory, and install dependencies using npm.

```bash
git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
npm install
```

--------------------------------

### Start Public HTTP Server

Source: https://github.com/nspady/google-calendar-mcp/blob/main/CLAUDE.md

Starts the server with an HTTP transport that is accessible from any host on the network.

```bash
npm run dev http:public
```

--------------------------------

### Docker Installation for Google Calendar MCP Server

Source: https://github.com/nspady/google-calendar-mcp/blob/main/README.md

Set up and run the Google Calendar MCP server using Docker. Copy your credentials file to the project directory before starting the Docker Compose service.

```bash
git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
cp /path/to/your/gcp-oauth.keys.json .
docker compose up
```

--------------------------------

### Start Basic HTTP Server

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/deployment.md

Starts the HTTP server on localhost, defaulting to port 3000. Use for local testing.

```bash
# Start on localhost only (default port 3000)
npm run start:http
```

--------------------------------

### Verify Setup and Run Integration Test

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/testing.md

Commands to check authentication status and execute a direct integration test.

```bash
# Check authentication status
npm run dev account:status

# Run a simple integration test
npm run test:integration:direct
```

--------------------------------

### Docker Deployment Quick Start

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/docker.md

A sequence of bash commands to set up and run the Google Calendar MCP Server using Docker Compose. It includes steps for copying credentials, setting permissions, configuring environment variables, building and starting the server, and initiating the authentication process.

```bash
# 1. Place OAuth credentials in project root
# * optional if you have already placed the file in the root of this project folder
cp /path/to/your/gcp-oauth.keys.json ./gcp-oauth.keys.json

# Ensure the file has correct permissions for Docker to read
chmod 644 ./gcp-oauth.keys.json

# 2. Configure environment (optional - uses stdio mode by default)
# The .env.example file contains all defaults. Copy if customization needed:
cp .env.example .env

# 3. Build and start the server
docker compose up -d

# 4. Authenticate (one-time setup)
# This will show the authentication URL that needs to be
# visited to give authorization to the application.
# Visit the URL and complete the OAuth process.
# Note: This runs the built auth-server.js (build happens during docker build)
docker compose exec calendar-mcp npm run auth
# Note: This step only needs to be done once unless the app is in testing mode
# in which case the tokens expire after 7 days 

# 5. Manage accounts from your browser
# Visit http://localhost:3000/accounts to add, re-authenticate, or remove accounts

# 5. Add to Claude Desktop config (see stdio Mode section below)
```

--------------------------------

### Clone and Setup Google Calendar MCP

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/docker.md

Clone the repository, set up OAuth credentials, and set file permissions for Docker.

```bash
git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp

# Place your OAuth credentials in the project root
cp /path/to/your/gcp-oauth.keys.json ./gcp-oauth.keys.json

# Ensure the file has correct permissions for Docker to read
chmod 644 ./gcp-oauth.keys.json
```

--------------------------------

### Start Server (stdio mode)

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/OVERVIEW.md

Use this command to start the Google Calendar MCP server in stdio mode, which is the default. No server startup is required for this mode.

```bash
npx @cocal/google-calendar-mcp
```

--------------------------------

### Local Installation of Google Calendar MCP Server

Source: https://github.com/nspady/google-calendar-mcp/blob/main/README.md

Clone the repository, install dependencies, and build the project for local usage. This allows for direct integration or configuration via environment variables.

```bash
git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
npm install
npm run build
```

--------------------------------

### Start Server with StdIO Transport

Source: https://github.com/nspady/google-calendar-mcp/blob/main/CLAUDE.md

Starts the server using the standard input/output (stdio) transport mechanism.

```bash
npm start
```

--------------------------------

### Start MCP Server

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/configuration.md

Start the MCP server using the default `stdio` transport. This is the default command if no other command is specified.

```bash
npx @cocal/google-calendar-mcp start
```

--------------------------------

### Direct Integration Test Setup

Source: https://github.com/nspady/google-calendar-mcp/blob/main/CLAUDE.md

Commands to set up credentials, test calendar, and authenticate for direct integration tests. Run these before executing integration tests.

```bash
# 1. Set credentials path
export GOOGLE_OAUTH_CREDENTIALS=./gcp-oauth.keys.json

# 2. Set test calendar (use "primary" or a specific calendar ID)
export TEST_CALENDAR_ID=primary

# 3. Authenticate test account
npm run dev auth:test

# 4. Run tests
npm run dev test:integration:direct
```

--------------------------------

### Find and Book Meeting Prompt Example

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/prompts-and-resources.md

This example demonstrates how to use the 'find-and-book-meeting' prompt to schedule a meeting. It includes the prompt text, arguments passed, and the expected AI response flow.

```text
Prompt: "Book a 1-hour meeting with alice@company.com and bob@company.com next week"

Arguments passed to prompt:
{
  "title": "Team Meeting",
  "attendeeEmails": ["alice@company.com", "bob@company.com"],
  "durationMinutes": 60,
  "windowStart": "2025-01-20T00:00:00",
  "windowEnd": "2025-01-24T23:59:59",
  "timeZone": "America/Los_Angeles"
}

AI Response (following the prompt):
1. Calls get-current-time
2. Calls get-freebusy for attendees' calendars
3. Proposes:
   - Slot 1 (recommended): Tue 10:00–11:00 (after all standups, morning focus)
   - Slot 2: Thu 14:00–15:00 (afternoon, less context switch)
   - Slot 3: Wed 16:00–17:00 (requires rescheduling other events)
4. Waits for user confirmation: "Let's do Tuesday 10am"
5. Calls create-event with confirmed slot
6. Returns: "Meeting scheduled: Team Meeting, Tue Jan 21, 10:00–11:00 AM"
```

--------------------------------

### Build and Start Docker Compose Services

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/docker.md

Builds the Docker images and starts the services defined in the docker-compose.yml file in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Start MCP with Command-Line Tool Filtering

Source: https://github.com/nspady/google-calendar-mcp/blob/main/README.md

Use the `--enable-tools` flag with the `npx` command to specify which tools the AI assistant can access. This helps reduce context usage and restrict capabilities.

```bash
npx @cocal/google-calendar-mcp start --enable-tools list-events,create-event,get-current-time
```

--------------------------------

### Start Authentication Server

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/authentication-and-utilities.md

Starts a local HTTP server to handle the OAuth2 browser-based authentication flow. Optionally opens a browser window for the user. Returns true on success or if tokens are already valid.

```typescript
const authServer = new AuthServer(oauth2Client);
const success = await authServer.start(true);
if (success) {
  console.log('Authentication complete');
} else {
  console.log('Failed to authenticate');
}
```

--------------------------------

### Example of Parsing Command-Line Arguments

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/authentication-and-utilities.md

Demonstrates how to use the parseArgs function to configure the server with HTTP transport and a specific port.

```typescript
const config = parseArgs(['--transport', 'http', '--port', '3000']);
// Returns: { transport: { type: 'http', port: 3000 } }
```

--------------------------------

### Run Development Menu

Source: https://github.com/nspady/google-calendar-mcp/blob/main/CLAUDE.md

Starts an interactive development menu that provides access to all available commands.

```bash
npm run dev
```

--------------------------------

### Start HTTP Server

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/OVERVIEW.md

This command starts the Google Calendar MCP server using the HTTP transport layer on a specified port. The default port is 3000.

```bash
npx @cocal/google-calendar-mcp start --transport http --port 3000
```

--------------------------------

### LLM Integration Test Setup (Claude/OpenAI)

Source: https://github.com/nspady/google-calendar-mcp/blob/main/CLAUDE.md

Commands to set up API keys and run LLM integration tests for Claude and OpenAI. These tests consume API credits and take longer to run.

```bash
# For Claude tests
export CLAUDE_API_KEY=sk-ant-...
npm run dev test:integration:claude

# For OpenAI tests
export OPENAI_API_KEY=sk-...
npm run dev test:integration:openai

# For both
npm run dev test:integration:all
```

--------------------------------

### Handler Implementation Pattern

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/handlers-architecture.md

A standard pattern for implementing `BaseToolHandler` subclasses. This example shows how to select an account, get a Calendar API instance, call the Google Calendar API, and return a structured response.

```typescript
import { BaseToolHandler } from './BaseToolHandler.js';
import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
import { OAuth2Client } from 'google-auth-library';
import { createStructuredResponse } from '../../utils/response-builder.js';

export class MyToolHandler extends BaseToolHandler {
  async runTool(
    args: MyToolInput,
    accounts: Map<string, OAuth2Client>
  ): Promise<CallToolResult> {
    try {
      // 1. Select account(s)
      const client = this.getClientForAccount(args.account, accounts);

      // 2. Get Calendar API instance
      const calendar = this.getCalendar(client);

      // 3. Call Google Calendar API
      const result = await calendar.events.list({
        calendarId: 'primary',
        // ... options
      });

      // 4. Convert to structured format
      const events = result.data.items?.map(e => convertGoogleEventToStructured(e)) || [];

      // 5. Return structured response
      return createStructuredResponse({
        events,
        totalCount: events.length
      });
    } catch (error) {
      this.handleGoogleApiError(error);
    }
  }
}
```

--------------------------------

### Local Installation Configuration for Google Calendar MCP

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/configuration.md

Configure Claude Desktop for local installation of the Google Calendar MCP using `npm run build`. This involves specifying the local command and build output path.

```json
{
  "mcpServers": {
    "google-calendar": {
      "command": "node",
      "args": ["/path/to/google-calendar-mcp/build/index.js"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/gcp-oauth.keys.json"
      }
    }
  }
}
```

--------------------------------

### Start and Authenticate Google Calendar MCP (HTTP Mode)

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/docker.md

Build and start the server in HTTP mode, then perform the one-time authentication. This step is required for HTTP mode.

```bash
# Build and start the server in HTTP mode
docker compose up -d

# Authenticate (one-time setup)
# Note: This runs the built auth-server.js (build happens during docker build)
docker compose exec calendar-mcp npm run auth
# This will show authentication URLs (visit the displayed URL)
# This step only needs to be done once unless the app is in testing mode
# in which case the tokens expire after 7 days 

# Verify server is running
curl http://localhost:3000/health
# Should return: {"status":"healthy","server":"google-calendar-mcp","timestamp":"YYYY-MM-DDT00:00:00.000"}
```

--------------------------------

### Multi-Calendar Booking Arguments

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/prompts-and-resources.md

This example shows how to specify multiple accounts for checking availability when booking a meeting across different calendars.

```json
{
  "title": "One-on-one",
  "attendeeEmails": ["david@partner.com"],
  "durationMinutes": 30,
  "windowStart": "2025-01-20T00:00:00",
  "windowEnd": "2025-01-24T23:59:59",
  "account": ["work", "personal"]
}
```

--------------------------------

### Token Storage File Format

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/authentication-and-utilities.md

Example JSON structure for storing authentication tokens for multiple accounts.

```json
{
  "default": {
    "type": "authorized_user",
    "client_id": "...",
    "client_secret": "...",
    "refresh_token": "...",
    "access_token": "...",
    "expiry_date": 1234567890
  },
  "work": {
    "type": "authorized_user",
    ...
  }
}
```

--------------------------------

### Manage Accounts via CLI

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/authentication.md

Use the command line interface for initial setup or scripting to add, list, or clear Google accounts. The 'auth' command requires an account ID, while 'list' and 'clear' can operate on all accounts or a specified one.

```bash
npm run account auth work      # Add "work" account
```

```bash
npm run account auth personal  # Add "personal" account
```

```bash
npm run account list           # List all accounts + status
```

```bash
npm run account clear work     # Remove an account
```

--------------------------------

### Initiate Account Authentication (JavaScript)

Source: https://github.com/nspady/google-calendar-mcp/blob/main/src/web/accounts.html

Starts the OAuth authentication flow for a new account by requesting an authorization URL from the server. Opens the URL in a popup window.

```javascript
async function addAccount(accountId) { try { // Get OAuth URL from server const response = await fetch(API_BASE, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ accountId }) }); const data = await response.json(); if (!response.ok) { throw new Error(data.message || 'Failed to initiate OAuth flow'); } // Open OAuth URL in popup const popup = window.open( data.authUrl, 'oauth', 'width=600,height=700,left=100,top=100' ); if (!popup) { showMessage('Popup blocked. 
```

--------------------------------

### Re-authenticate using NPX

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/authentication.md

Set the credentials path and run the auth command for NPX installations when tokens expire or become invalid.

```bash
# Set your credentials path first
export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/gcp-oauth.keys.json"

# Run the auth command
npx @cocal/google-calendar-mcp auth
```

--------------------------------

### Daily Agenda Brief Prompt Example

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/prompts-and-resources.md

Illustrates how to request a daily agenda brief. The AI response shows the sequence of tool calls and the structured output it generates, including priorities, risks, focus blocks, and a checklist.

```text
Prompt: "Give me my daily agenda brief for tomorrow"

AI Response (following the prompt):
1. Calls get-current-time to confirm today's date
2. Calls list-events for tomorrow
3. Generates structured brief:
   - Priorities: Quarterly review prep, 1:1 with manager, team standup
   - Risks: Back-to-back 11am–1pm (no lunch), QR prep time insufficient before 2pm
   - Focus blocks: 8:00–10:00am (deep work), 3:00–5:00pm (execution)
   - Checklist: Collect slides (by 1pm), review Q3 notes (by 1:30pm)
```

--------------------------------

### Get Calendar Timezone Example

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/handlers-architecture.md

Fetches the default timezone for a specified calendar. The returned value is an IANA timezone string, such as 'America/Los_Angeles'.

```typescript
const tz = await this.getCalendarTimezone('primary', client);
```

--------------------------------

### Transport Selection - Start Method

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/OVERVIEW.md

Selects the appropriate transport layer for the Google Calendar MCP Server, supporting stdio for direct process communication and HTTP for remote access via a RESTful API.

```typescript
// stdio: Direct process communication for Claude Desktop
// HTTP: RESTful API with server-sent events for remote access
```

--------------------------------

### Get Google Calendar API Client Example

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/handlers-architecture.md

Retrieves a configured Google Calendar API client instance with a 3-second timeout. This client is used to interact with the Calendar API.

```typescript
const calendar = this.getCalendar(client);
const event = await calendar.events.get({
  calendarId: 'primary',
  eventId: 'abc123'
});
```

--------------------------------

### Get Clients For Accounts Example

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/handlers-architecture.md

Use this method to retrieve one or more OAuth2Clients for multi-account operations. If no account IDs are provided, it returns all authenticated accounts. It validates that all specified account IDs exist.

```typescript
const clientMap = this.getClientsForAccounts(args.account, accounts);
```

--------------------------------

### Build and Authenticate Project

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/development.md

Build the project and authenticate the main and test accounts.

```bash
npm run build
npm run auth                # Authenticate main account
npm run dev auth:test       # Authenticate test account (used for integration tests)
```

--------------------------------

### Get Client For Account Or First Example

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/handlers-architecture.md

Use this method to retrieve an OAuth2Client for a specific account ID, or the first available account if none is specified. Throws an error if no accounts are connected. Suitable for read-only operations.

```typescript
const client = this.getClientForAccountOrFirst(args.account, accounts);
```

--------------------------------

### Get Client For Account Example

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/handlers-architecture.md

Use this method to retrieve an OAuth2Client for a specific account ID or auto-select the default if only one account is connected. Throws an error if multiple accounts exist and none is specified, or if no accounts are connected.

```typescript
const client = this.getClientForAccount(args.account, accounts);
```

--------------------------------

### Configure OAuth Credentials Path and Authenticate

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/configuration.md

Set the GOOGLE_OAUTH_CREDENTIALS environment variable to the path of your downloaded JSON credentials file. Then, run the authentication command.

```bash
export GOOGLE_OAUTH_CREDENTIALS="/path/to/gcp-oauth.keys.json"
npx @cocal/google-calendar-mcp auth
```

--------------------------------

### Deploy to Heroku

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/deployment.md

Create a Heroku application, set the Node.js buildpack, configure necessary environment variables, and deploy your code using Git.

```bash
# Create app
heroku create your-calendar-mcp

# Set buildpack
heroku buildpacks:set heroku/nodejs

# Configure
heroku config:set TRANSPORT=http
heroku config:set GOOGLE_OAUTH_CREDENTIALS=./gcp-oauth.keys.json

# Deploy
git push heroku main
```

--------------------------------

### Build Project

Source: https://github.com/nspady/google-calendar-mcp/blob/main/CLAUDE.md

Builds the project using esbuild, outputting to the build directory.

```bash
npm run build
```

--------------------------------

### Deploy to Google Cloud Run

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/deployment.md

Build and push your container image to Google Container Registry, then deploy it to Cloud Run. Configure environment variables as needed.

```bash
# Build and push image
gcloud builds submit --tag gcr.io/PROJECT-ID/calendar-mcp

# Deploy
gcloud run deploy calendar-mcp \
  --image gcr.io/PROJECT-ID/calendar-mcp \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="TRANSPORT=http"
```

--------------------------------

### Get Current Time with Timezone

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/tools-reference.md

Call this function to get the current date and time in a specified timezone. It's useful for establishing context before creating events. Ensure the IANA timezone format is used.

```typescript
const result = await getCurrentTime({
  timeZone: 'America/New_York'
});

console.log(`Current time: ${result.currentTime} (${result.dayOfWeek})`);
console.log(`Timezone: ${result.timezone} (UTC${result.offset})`);
console.log(`DST: ${result.isDST ? 'Yes' : 'No'}`);

// Use in event creation
const now = new Date(result.currentTime);
const nextWeek = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000);
// ... create event starting nextWeek
```

--------------------------------

### Complex Search Query Example

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/advanced-usage.md

Combine multiple search criteria to find specific events. This example searches for meetings with a specific team, at a particular location, and with a duration longer than an hour within a defined future timeframe.

```natural-language
"Find all meetings with the sales team at the main office that are longer than an hour in the next two weeks"
```

--------------------------------

### Exported Functions

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/OVERVIEW.md

Provides top-level functions for starting the MCP server and running the OAuth authentication flow.

```APIDOC
## Exported Functions

### `main()`

#### Description
Starts the MCP server with default transport configuration.

### `runAuthServer(accountId?)`

#### Description
Initiates and runs the OAuth authentication flow for a given account ID.
```

--------------------------------

### Set Up Direct Google Calendar Integration Tests

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/testing.md

Configure environment variables for Google OAuth credentials and test calendar ID. Authenticate the test account using the provided npm script.

```bash
# Set environment variables
export GOOGLE_OAUTH_CREDENTIALS="path/to/your/oauth-credentials.json"
export TEST_CALENDAR_ID="your-test-calendar-id"

# Authenticate test account
npm run dev auth:test
```

--------------------------------

### create-event

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/MANIFEST.txt

Creates a new event in a specified calendar. Requires details about the event, including summary, start and end times.

```APIDOC
## create-event

### Description
Creates a new event in a specified calendar. Requires details about the event, including summary, start and end times.

### Method
POST

### Endpoint
/tools/create-event

### Parameters
#### Request Body
- **calendarId** (string) - Required - The ID of the calendar to create the event in.
- **event** (object) - Required - The event object to create.
  - **summary** (string) - Required - The title or summary of the event.
  - **start** (object) - Required - The start time of the event.
    - **dateTime** (string) - The date and time of the event start (RFC3339 format).
    - **timeZone** (string) - The time zone of the event start.
  - **end** (object) - Required - The end time of the event.
    - **dateTime** (string) - The date and time of the event end (RFC3339 format).
    - **timeZone** (string) - The time zone of the event end.
  - **description** (string) - Optional - The detailed description of the event.
  - **attendees** (array) - Optional - A list of attendees for the event.
  - **reminders** (object) - Optional - Reminder settings for the event.

### Request Example
{
  "calendarId": "primary",
  "event": {
    "summary": "Team Standup",
    "start": {
      "dateTime": "2024-07-18T09:00:00-07:00",
      "timeZone": "America/Los_Angeles"
    },
    "end": {
      "dateTime": "2024-07-18T09:15:00-07:00",
      "timeZone": "America/Los_Angeles"
    },
    "description": "Daily team sync meeting.",
    "attendees": [
      {"email": "member1@example.com"},
      {"email": "member2@example.com"}
    ],
    "reminders": {
      "useDefault": false,
      "overrides": [
        {"method": "email", "minutes": 10}
      ]
    }
  }
}

### Response
#### Success Response (200)
- **createdEvent** (object) - The newly created event object, including its ID.
  - **id** (string) - The unique identifier for the created event.
  - **status** (string) - The status of the event (e.g., 'confirmed').

#### Response Example
{
  "createdEvent": {
    "id": "newEventId123",
    "status": "confirmed"
  }
}
```

--------------------------------

### Configure Environment for HTTP Mode

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/docker.md

Set up the .env file for HTTP mode, ensuring the TRANSPORT variable is set to 'http'.

```bash
# Clone and setup
git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp

# Place your OAuth credentials in the project root
cp /path/to/your/gcp-oauth.keys.json ./gcp-oauth.keys.json

# Ensure the file has correct permissions for Docker to read
chmod 644 ./gcp-oauth.keys.json

# Configure for HTTP mode
# Copy .env.example which has defaults (TRANSPORT=stdio, HOST=127.0.0.1, PORT=3000)
cp .env.example .env

# Change TRANSPORT to http (other defaults are already correct)
# Update TRANSPORT=stdio to TRANSPORT=http in .env
# Note: HOST defaults to 127.0.0.1 for security (localhost only)
```

--------------------------------

### Run Unit and Integration Tests

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/testing.md

Execute unit tests, direct integration tests, or all tests using npm scripts. Unit tests require no authentication, while integration tests require Google authentication.

```bash
npm test                 # Unit tests (no auth required)
npm run test:integration # Direct integration tests only (requires Google auth)
npm run test:integration:all # All integration tests (direct + multi-account + LLM + docker)
npm run test:all         # Unit + all integration tests
```

--------------------------------

### Run Direct Integration Tests

Source: https://github.com/nspady/google-calendar-mcp/blob/main/CLAUDE.md

Executes direct integration tests. This is the recommended command for development.

```bash
npm run dev test:integration:direct
```

--------------------------------

### Get Singleton Instance of CalendarRegistry

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/authentication-and-utilities.md

Retrieves the singleton instance of the `CalendarRegistry` class. Use this to access calendar management functionalities.

```typescript
static getInstance(): CalendarRegistry
```

--------------------------------

### Add Google Account via CLI

Source: https://github.com/nspady/google-calendar-mcp/blob/main/README.md

Use this command-line interface command to add a new Google account with a specified nickname for authentication.

```bash
npm run account auth <nickname>
```

--------------------------------

### Run Multi-Account Integration Tests

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/testing.md

Set environment variables to enable and configure multi-account integration tests. Ensure all listed accounts are already authenticated.

```bash
export MULTI_ACCOUNT_TESTS=true
export MULTI_ACCOUNT_IDS=work,personal
npm run test:integration:multi-account
```

--------------------------------

### Get Unified Calendars from Accounts

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/authentication-and-utilities.md

Fetches and deduplicates calendars from multiple accounts, tracking access roles. Results are cached for performance.

```typescript
async getUnifiedCalendars(accounts: Map<string, OAuth2Client>): Promise<CalendarInfo[]>
```

--------------------------------

### Get Account Mode

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/authentication-and-utilities.md

Retrieves the currently configured account mode for the CLI, defaulting to 'default' if the GOOGLE_ACCOUNT_MODE environment variable is not set.

```typescript
getAccountMode(): string
```

--------------------------------

### Run Development and Testing Commands

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/development.md

Commands for interactive development, building, linting, and running tests.

```bash
npm run dev         # Interactive development menu
npm run build       # Build project  
npm run lint        # Type-check with TypeScript (no emit)
npm test            # Run tests
```

--------------------------------

### Docker Run Deployment (stdio)

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/deployment.md

Deploys the Google Calendar MCP Server in stdio mode using `docker run`. Requires creating a volume for token storage.

```bash
# Create volume for token storage
docker volume create mcp-tokens

# stdio mode
docker run -i \
  -v ./gcp-oauth.keys.json:/usr/src/app/gcp-oauth.keys.json:ro \
  -v mcp-tokens:/home/nodejs/.config/google-calendar-mcp \
  -e TRANSPORT=stdio \
  --name calendar-mcp \
  google-calendar-mcp
```

--------------------------------

### Throwing McpError Example

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/authentication-and-utilities.md

Demonstrates how to throw an McpError with an InvalidRequest code and a descriptive message. This is useful for signaling invalid input or missing parameters.

```typescript
throw new McpError(
  ErrorCode.InvalidRequest,
  'Calendar ID is required'
);
```

--------------------------------

### Test Google Calendar MCP with cURL (HTTP Mode)

Source: https://github.com/nspady/google-calendar-mcp/blob/main/docs/docker.md

Execute comprehensive HTTP tests using cURL scripts provided in the examples directory.

```bash
# Run comprehensive HTTP tests
bash examples/http-with-curl.sh

# Or test specific endpoint
bash examples/http-with-curl.sh http://localhost:3000
```

--------------------------------

### Verify Credentials File Path and Permissions

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/configuration.md

Troubleshoot 'Credentials file not found' errors by verifying the absolute path to your credentials file and ensuring it has the correct read/write permissions.

```bash
# Verify file path is absolute and correct
ls -la /path/to/gcp-oauth.keys.json

# Verify permissions
chmod 600 /path/to/gcp-oauth.keys.json
```

--------------------------------

### Verify Type Coverage in Documentation

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/MANIFEST.txt

Counts the number of type headings (lines starting with '##') in the types.md file. This helps ensure comprehensive documentation of response types.

```shell
grep "^##" /workspace/home/output/types.md | grep "^##" | wc -l
```

--------------------------------

### GoogleCalendarMcpServer Class

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/OVERVIEW.md

Represents the main server class for the Google Calendar MCP. It allows for initialization, starting the server, and retrieving the underlying MCP server instance.

```APIDOC
## Class: GoogleCalendarMcpServer

### Description
Provides methods to manage the Google Calendar MCP server instance.

### Methods

- **`constructor(config: ServerConfig)`**: Initializes the server with the provided configuration.
- **`initialize(): Promise<void>`**: Asynchronously initializes the server.
- **`start(): Promise<void>`**: Asynchronously starts the server.
- **`getServer(): McpServer`**: Returns the underlying McpServer instance.
```

--------------------------------

### Entry Point Flow - Auth Command

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/OVERVIEW.md

Handles the 'auth' command by calling `runAuthServer`. This function is responsible for initiating the authentication process for a given account ID.

```typescript
// Routes to `auth`, `start`, `version`, or `help` commands
// For `auth`: calls `runAuthServer(accountId?)`
// For `start` (default): calls `main()`
```

--------------------------------

### GetCurrentTimeResponse Interface

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/types.md

Defines the structure for a response when getting the current time. It includes the current time, timezone, offset, and day of the week, with an optional DST indicator.

```typescript
interface GetCurrentTimeResponse {
  currentTime: string
  timezone: string
  offset: string
  isDST?: boolean
  dayOfWeek: string
}
```

--------------------------------

### Authenticate Main Account

Source: https://github.com/nspady/google-calendar-mcp/blob/main/CLAUDE.md

Initiates the authentication process for the main user account.

```bash
npm run auth
```

--------------------------------

### Checking External Calendars with UTC Timezone

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/prompts-and-resources.md

This example demonstrates how to check availability with an external calendar by specifying a UTC timezone for accurate comparison across different locations.

```json
{
  "title": "London Sync",
  "attendeeEmails": ["manager@london-office.co.uk"],
  "durationMinutes": 30,
  "windowStart": "2025-01-20T00:00:00",
  "windowEnd": "2025-01-24T23:59:59",
  "timeZone": "UTC"  # Use UTC for multiple timezone comparison
}
```

--------------------------------

### Server Initialization

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/OVERVIEW.md

Initializes the Google Calendar MCP Server, including setting up the OAuth2 client, token manager, loading authenticated accounts, and handling startup authentication.

```typescript
// Initializes OAuth2 client and token manager
// Loads all authenticated accounts
// Handles startup authentication (different for stdio vs HTTP)
// Registers tools, prompts, and resources
```

--------------------------------

### Nginx Reverse Proxy Configuration

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/configuration.md

Example Nginx configuration for setting up a reverse proxy to secure and expose the Google Calendar MCP service. Ensure TLS/SSL is properly configured.

```nginx
server {
  listen 443 ssl; 
  server_name calendar.example.com;
  
  ssl_certificate /etc/ssl/certs/cert.pem;
  ssl_certificate_key /etc/ssl/private/key.pem;
  
  location / {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
}
```

--------------------------------

### Daily Agenda Brief for Multiple Accounts

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/prompts-and-resources.md

Demonstrates how to specify multiple accounts to include in the daily agenda brief by passing an array of account nicknames.

```text
Prompt: "Give me my daily agenda brief for both work and personal accounts"

Arguments passed to prompt:
{
  "account": ["work", "personal"]
}
```

--------------------------------

### Example Error Message for Invalid Tool Names

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/configuration.md

This error message is displayed when an invalid tool name is provided during tool filtering configuration. It lists the available tools for reference.

```text
Invalid tool name(s): invalid-tool.
Available tools: list-calendars, list-events, search-events, get-event, list-colors, create-event, create-events, update-event, delete-event, get-freebusy, get-current-time, respond-to-event, manage-accounts
```

--------------------------------

### Get Event Details with Google Calendar MCP

Source: https://github.com/nspady/google-calendar-mcp/blob/main/_autodocs/tools-reference.md

Retrieve details of a specific event by ID. Specify the calendar ID, event ID, and optionally account and fields to include.

```typescript
const result = await getEvent({
  calendarId: 'primary',
  eventId: 'abc123xyz789',
  fields: ['description', 'attendees', 'conferenceData']
});

console.log(`Event: ${result.event.summary}`);
console.log(`Start: ${result.event.start.dateTime}`);
```