@waleedyousaf07/mcp-google-calendar

Thin Google Calendar MCP server for any MCP-compatible client. It runs over stdio, uses direct Google Calendar REST calls, and keeps the tool surface small.

Quick Start

npx @waleedyousaf07/mcp-google-calendar@latest

OAuth Setup

Create a Google OAuth Desktop app, enable the Google Calendar API, and use one of:

MCP_GOOGLE_CALENDAR_CLIENT_ID=your_client_id
MCP_GOOGLE_CALENDAR_CLIENT_SECRET=your_client_secret

Or point to the downloaded OAuth JSON file:

MCP_GOOGLE_CALENDAR_CLIENT_CREDENTIALS_PATH=/absolute/path/to/google-oauth-client.json

Optional:

MCP_GOOGLE_CALENDAR_USE_KEYTAR=true

If MCP_GOOGLE_CALENDAR_USE_KEYTAR=true but keytar is unavailable, the server falls back to a plaintext token file in the OS config directory.

Scopes

This package uses:

• https://www.googleapis.com/auth/calendar.events
• https://www.googleapis.com/auth/calendar.calendarlist.readonly

That covers listing calendars plus reading, creating, updating, and deleting events.

Tools

• calendar.listCalendars
• calendar.listEvents
• calendar.getEvent
• calendar.createEvent
• calendar.updateEvent
• calendar.deleteEvent

Client Config Example

Any MCP client that can launch a stdio server can use this package. Use npx as the default command so the config stays portable across macOS, Linux, and Windows:

{
  "id": "google-calendar",
  "transport": "stdio",
  "command": [
    "npx",
    "--yes",
    "@waleedyousaf07/mcp-google-calendar@latest"
  ],
  "headers": {}
}

If your MCP client supports OS-specific overrides, only add a Windows-specific npx.cmd path there. Keep the default config on plain npx.

Troubleshooting

• Browser did not open: the server prints the Google auth URL to stderr. Open it manually in a browser on the same machine. This is expected on headless Linux or any machine without a desktop opener.
• invalid_grant: your stored refresh token is no longer valid. Delete the saved token from your user config directory and authorize again.
• Permission errors: confirm the Google Calendar API is enabled in your Google Cloud project and the OAuth client is a Desktop app.

Local Commands

pnpm i
pnpm build
pnpm test
node dist/cli.js