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: "colleague@example.com" }],
  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)