google-calendar-mcp-lib

A Google Calendar MCP server written in TypeScript. Can be run as a stdio MCP server or used directly as a library with imported functions.

Tools

All tools are prefixed with googleCalendar:

| Tool | Description | |---|---| | googleCalendarListCalendars | List all calendars accessible by the authenticated user | | googleCalendarListEvents | List events from a calendar, with optional filters | | googleCalendarGetEvent | Get a specific event by ID | | googleCalendarCreateEvent | Create a new event | | googleCalendarUpdateEvent | Update an existing event | | googleCalendarDeleteEvent | Delete an event |

Authentication

Every tool accepts optional auth parameters. If not provided, the server falls back to environment variables.

| Parameter | Environment variable | |---|---| | accessToken | GOOGLE_ACCESS_TOKEN | | refreshToken | GOOGLE_REFRESH_TOKEN | | clientId | GOOGLE_CLIENT_ID | | clientSecret | GOOGLE_CLIENT_SECRET |

Only accessToken is required. clientId and clientSecret are needed only if you want the client to auto-refresh expired tokens using the refreshToken.

To obtain credentials, create an OAuth 2.0 client in the Google Cloud Console with the https://www.googleapis.com/auth/calendar scope.

Usage

As an MCP stdio server

Build and run:

npm install
npm run build
node dist/index.js

Or during development:

npm run dev

Claude Desktop configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "google-calendar": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "GOOGLE_ACCESS_TOKEN": "ya29.xxx",
        "GOOGLE_REFRESH_TOKEN": "1//xxx",
        "GOOGLE_CLIENT_ID": "xxx.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "xxx"
      }
    }
  }
}

As a library

Import and call functions directly, passing credentials per-call:

import {
  googleCalendarListEvents,
  googleCalendarCreateEvent,
  googleCalendarDeleteEvent,
} from "./dist/api.js";

// List upcoming events
const events = await googleCalendarListEvents({
  accessToken: "ya29.xxx",
  calendarId: "primary",
  timeMin: new Date().toISOString(),
  maxResults: 10,
});

// Create an event
const event = await googleCalendarCreateEvent({
  accessToken: "ya29.xxx",
  summary: "Team standup",
  start: { dateTime: "2026-03-10T09:00:00-08:00", timeZone: "America/Los_Angeles" },
  end:   { dateTime: "2026-03-10T09:30:00-08:00", timeZone: "America/Los_Angeles" },
  attendees: [{ email: "[email protected]" }],
  sendUpdates: "all",
});

// Delete it
await googleCalendarDeleteEvent({
  accessToken: "ya29.xxx",
  eventId: event.id,
});

Or rely on environment variables and omit auth params entirely:

export GOOGLE_ACCESS_TOKEN=ya29.xxx

const calendars = await googleCalendarListCalendars({});

Development

npm install          # install dependencies
npm run build        # compile TypeScript → dist/
npm run dev          # run stdio server with tsx (no build step)

Project structure

src/
  auth.ts      — credential resolution and OAuth2Client factory
  calendar.ts  — Google Calendar API v3 wrappers
  tools.ts     — callable functions + Zod input schemas
  server.ts    — MCP server with all tools registered
  api.ts       — library entry point (re-exports everything)
  index.ts     — stdio entry point (bin)