Google Calendar

Google Calendar MCP Server creates a bridge between Google Calendar and Claude Desktop using the Model Context Protocol (MCP). It lets you view, create, update, and delete calendar events directly through natural language interactions, while handling authentication and data validation securely.

How to use

You interact with Google Calendar MCP Server through an MCP client integrated with Claude Desktop. Use natural language prompts to list events, create new events, modify existing ones, or remove events from your Google Calendar. You can also manage recurring events by providing recurrence rules when you create or update events. The server handles authentication, data validation, and secure storage of tokens, so you can focus on your scheduling needs.

How to install

Prerequisites: You need Node.js and npm installed on your machine.

Install the MCP server package globally so you can run it from anywhere.

npm install -g @takumi0706/google-calendar-mcp

Configure your environment with Google OAuth credentials and optional security keys. Create a .env file with the following variables.

# Create a .env file with your Google OAuth credentials
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:4153/oauth2callback
# Optional: Token encryption key (auto-generated if not provided)
TOKEN_ENCRYPTION_KEY=32-byte-hex-key
# Optional: Auth server port and host (default port: 4153, host: localhost)
AUTH_PORT=4153
AUTH_HOST=localhost
# Optional: MCP server port and host (default port: 3000, host: localhost)
PORT=3000
HOST=localhost
# Optional: Enable manual authentication (useful when localhost is not accessible)
USE_MANUAL_AUTH=true

Start the server or configure Claude Desktop to load the MCP server via the provided CLI. The recommended integration method uses a local MCP runner.

Configuration and operational notes

The server is configured through environment variables and an optional Claude Desktop JSON profile that references the MCP server. Ensure your Google OAuth credentials are configured in Google Cloud Console and that the redirect URI matches your local setup.

In Claude Desktop, register the MCP server using the following JSON snippet. This config runs the MCP server via a local command and passes your Google credentials as environment variables.

{
  "mcpServers": {
    "google_calendar": {
      "command": "npx",
      "args": [
        "-y",
        "@takumi0706/google-calendar-mcp"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:4153/oauth2callback"
      }
    }
  }
}

Security considerations

OAuth tokens are kept in memory and not stored on disk. Tokens are encrypted with AES-256-GCM, and you should provide credentials securely via environment variables. The server uses PKCE with explicit code_verifier and code_challenge, and validates the state parameter to protect against CSRF.

Troubleshooting

If you encounter authentication or MCP communication issues, verify that your Google OAuth credentials are correct and that the redirect URI matches your setup. Ensure only a single instance of the MCP server is running and that Claude Desktop can reach localhost when using internal authentication.

Version history

Version 1.0.5 adds support for recurring events through the recurrence parameter in both createEvent and updateEvent tools, enabling direct creation and modification of recurring events.

Available tools

getEvents

Retrieve calendar events with optional filtering such as calendarId, timeMin, timeMax, maxResults, and orderBy.

createEvent

Create a new calendar event with details like summary, description, location, start/end times, attendees, colorId, and optional recurrence for recurring events.

updateEvent

Update an existing event by merging provided fields with existing data; supports partial updates and updating recurrence rules.

deleteEvent

Delete an existing calendar event by its eventId.

authenticate

Re-authenticate with Google Calendar to switch accounts without restarting the server.