GongRzhe_Calendar

Mirror of https://github.com/GongRzhe/Calendar-MCP-Server

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio cskwork-gongrzhe_calendar-mcp-server npx @gongrzhe/server-calendar-mcp \
  --env GOOGLE_CLIENT_ID="your_client_id_here" \
  --env GOOGLE_CLIENT_SECRET="your_client_secret_here" \
  --env GOOGLE_REFRESH_TOKEN="your_refresh_token_here"

How to use

This MCP server provides Google Calendar integration for Claude Desktop, enabling AI assistants to manage your Google Calendar events through natural language interactions. By running the server package, you gain capabilities to create, list, update, retrieve, and delete events, as well as query events within a time range. The integration relies on Google Calendar API and OAuth2 credentials to securely access your calendar data. To use it, configure the server in Claude Desktop with the appropriate OAuth credentials and point Claude to the MCP server via the calendar module. Once connected, you can issue natural-language requests such as creating a new event with a title, time, description, and location; listing upcoming events; updating event details; or deleting events by ID. The tool set mirrors the common calendar operations exposed by Google Calendar API, but is designed to be invoked within Claude’s context for conversational flows.

How to install

Prerequisites:

Node.js and npm installed on your machine
A Google Cloud project with Calendar API enabled
OAuth 2.0 credentials (client ID and client secret) and a refresh token for accessing Google Calendar

Installation steps:

Install the MCP server package via npm (manual):

npm install @gongrzhe/server-calendar-mcp

Alternatively, install via Smithery integration (automatic):

npx -y @smithery/cli install @gongrzhe/server-calendar-mcp --client claude

Prepare OAuth credentials for Claude Desktop configuration:

Obtain GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REFRESH_TOKEN from Google Cloud Console and OAuth Playground as described in the README.

Configure the MCP server in Claude Desktop or your app wiring as shown in the example configuration:

{
  "calendar": {
    "command": "npx",
    "args": [
      "@gongrzhe/server-calendar-mcp"
    ],
    "env": {
      "GOOGLE_CLIENT_ID": "your_client_id_here",
      "GOOGLE_CLIENT_SECRET": "your_client_secret_here",
      "GOOGLE_REFRESH_TOKEN": "your_refresh_token_here"
    }
  }
}

Start the server and verify it connects to Google Calendar. Ensure your environment has network access to Google APIs and that the OAuth tokens are valid.

Additional notes

Tips and considerations:

Keep Google API credentials secure; avoid committing them to version control.
The refresh token is long-lived but should be rotated periodically for security.
If you encounter OAuth token errors, re-run the OAuth flow to refresh tokens and update GOOGLE_REFRESH_TOKEN.
The MCP server relies on the Google Calendar API; ensure your project has proper API enablement and that the service account/user has calendar access.
When running via npx, ensure your environment is online to fetch the package; if offline, consider using a local install of the package.
If Claude Desktop requires specific environment variable names, follow the provided keys exactly: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN.
Monitor quota usage in Google Cloud Console to avoid hitting API limits during bulk operations.