Google Calendar MCP Server

All tools in the Google Calendar MCP server support an optional account parameter to control which authenticated accounts are used for the operation. The parameter accepts a string (single account ID) or a string[] (array of account IDs).

Parameter Behavior by Tool Type

Example: Merging results from multiple accounts

When using a query tool like list-events, providing an array of accounts will return a merged, chronologically sorted list of events from all specified sources.

// Example tool parameter shape
{
  "account": ["work", "personal"],
  "timeMin": "2023-01-01T00:00:00Z"
}

The server implements a Unified Calendar Registry to handle cases where the same calendar is accessible via multiple authenticated accounts with different permission levels.

Deduplication Logic

1. Discovery: The server queries all authenticated accounts to aggregate available calendars.
2. Grouping: Calendars are grouped by their unique calendarId (e.g., abc123@group.calendar.google.com).
3. Permission Ranking: Permissions are ranked as follows:
   • owner (highest)
   • writer
   • reader (lowest)
4. Write Operations: When a mutation (create/update/delete) is performed and no account is specified, the server automatically uses the preferredAccount (the one with the highest permission level for that specific calendar).
5. Read Operations: Read operations can use any account that has access, though they prefer the preferredAccount for reliability.

The project uses an automated system to inject intelligent behaviors into MCP tools without modifying the core handler logic. This is achieved through a three-part mechanism:

1. Configuration: You define which behaviors (e.g., ContextAware, DuplicateDetection) apply to which tools in config/tool-enhancements.ts.
2. Auto-Discovery Registry: The ToolRegistry class automatically discovers handlers and wraps them with the configured behaviors during server startup.
3. Behavior Injection: Behaviors intercept the tool arguments and inject additional data (like _context or _duplicateCheck) before they reach the handler's runTool method.

This allows for 'Zero Handler Changes'—existing handlers receive enhanced arguments automatically based on the configuration.

// 1. Configuration in config/tool-enhancements.ts
export const toolEnhancements = {
  'create-event': [ContextAware, DuplicateDetection, SmartDefaults],
  'list-events': [ContextAware, PatternRecognition],
};

// 2. Registry application in tools/registry.ts
export class ToolRegistry {
  static async registerAll(server: McpServer) {
    const handlers = await this.discoverHandlers();
    for (const [name, HandlerClass] of handlers) {
      const enhancements = toolEnhancements[name] || [];
      const enhancedHandler = this.applyEnhancements(HandlerClass, enhancements);
      server.tool(name, enhancedHandler.description, enhancedHandler.schema, 
        (args) => executeWithHandler(enhancedHandler, args)
      );
    }
  }
}

// 3. Usage in a handler
export class CreateEventHandler extends BaseToolHandler {
  async runTool(args: any, oauth2Client: OAuth2Client) {
    const context = args._context; // Automatically injected by ContextAware
    const isLikelyDuplicate = args._duplicateCheck; // Automatically injected by DuplicateDetection
    // ... core logic
  }
}

The server supports multiple authenticated Google accounts (e.g., work, personal). Tools behave differently depending on whether they are 'multi-account' or 'single-account' tools.

Multi-account tools

These tools (e.g., list-events, list-calendars, search-events, get-freebusy) accept either a single account string or an array of account strings via the account parameter.

• Omit account: Queries all authenticated accounts and merges the results.
• account: "name": Queries only that specific account.
• account: ["name1", "name2"]: Queries and merges the specified accounts.

Single-account tools

These tools (e.g., create-event, update-event, delete-event, get-event, get-current-time, list-colors) accept only one account.

• Omit account: The server auto-selects the best account. For write tools, it picks the account with write permission to the target calendar.
• account: "name": Uses that specific account.

// Read-only: Query all accounts (auto-merge)
use_tool("list-events", {
  timeMin: "2025-02-01T00:00:00",
  timeMax: "2025-02-01T23:59:59"
});

// Read-only: Query specific accounts
use_tool("list-events", {
  account: ["work", "personal"],
  timeMin: "2025-02-01T00:00:00",
  timeMax: "2025-02-01T23:59:59"
});

// Write: Explicitly pick account (must be a single string)
use_tool("create-event", {
  calendarId: "team@company.com",
  summary: "Status update",
  account: "work",
  start: "2025-02-01T10:00:00",
  end: "2025-02-01T11:00:00"
});

// Write: Auto-select account (finds account with write access)
use_tool("create-event", {
  calendarId: "team@company.com",
  summary: "Status update",
  start: "2025-02-01T10:00:00",
  end: "2025-02-01T11:00:00"
});