Google Calendar MCP server

This Google Calendar MCP server provides seamless Google Calendar integration for AI assistants like Claude, allowing you to manage events, check availability, and handle calendar operations through natural conversation.

Prerequisites

Before installation, you'll need:

1. A Google Cloud project with the Calendar API enabled
2. OAuth 2.0 credentials (Desktop app type)

Google Cloud Setup

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Calendar API for your project
4. Create OAuth 2.0 credentials:
   • Go to Credentials
   • Click "Create Credentials" > "OAuth client ID"
   • Choose "User data" for the type of data the app will access
   • Add your app name and contact information
   • Add the following scopes (optional):
     • https://www.googleapis.com/auth/calendar.events and https://www.googleapis.com/auth/calendar
   • Select "Desktop app" as the application type
   • Save the auth key for later use
   • Add your email address as a test user under the Audience screen

Installation Options

Option 1: Using npx (Recommended)

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["@cocal/google-calendar-mcp"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
      }
    }
  }
}

⚠️ Important: When using npx, you must specify the credentials file path using the GOOGLE_OAUTH_CREDENTIALS environment variable.

Option 2: Local Installation

git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
npm install
npm run build

Then add to Claude Desktop config using the local path or by specifying the path with the GOOGLE_OAUTH_CREDENTIALS environment variable.

Option 3: Docker Installation

git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
cp /path/to/your/gcp-oauth.keys.json .
docker compose up

First Run

1. Start Claude Desktop
2. The server will prompt for authentication on first use
3. Complete the OAuth flow in your browser
4. You're ready to use calendar features!

Example Usage

The Google Calendar MCP server enables powerful calendar interactions:

1. Cross-calendar availability:

   Please provide availability looking at both my personal and work calendar for this upcoming week.
   I am looking for a good time to meet with someone in London for 1 hr.
   

2. Add events from images:

   Add this event to my calendar based on the attached screenshot.
   

   Supported image formats: PNG, JPEG, GIF

3. Calendar analysis:

   What events do I have coming up this week that aren't part of my usual routine?
   

4. Check attendance:

   Which events tomorrow have attendees who have not accepted the invitation?
   

5. Auto coordinate events:

   Here's some available that was provided to me by someone. {available times}
   Take a look at the times provided and let me know which ones are open on my calendar.
   

Available Tools

Tool	Description
list-calendars	List all available calendars
list-events	List events with date filtering
search-events	Search events by text query
create-event	Create new calendar events
update-event	Update existing events
delete-event	Delete events
get-freebusy	Check availability across calendars
list-colors	List available event colors

Configuration

Environment Variables:

• GOOGLE_OAUTH_CREDENTIALS - Path to OAuth credentials file
• GOOGLE_CALENDAR_MCP_TOKEN_PATH - Custom token storage location (optional)

Claude Desktop Config Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Troubleshooting

OAuth Credentials File Not Found

• For npx users: You must specify the credentials file path using GOOGLE_OAUTH_CREDENTIALS
• Verify file paths are absolute and accessible

Authentication Errors

• Ensure your credentials file contains credentials for a Desktop App type
• Verify your user email is added as a Test User in the Google Cloud OAuth Consent screen
• Try deleting saved tokens and re-authenticating
• Check that no other process is blocking ports 3000-3004

Tokens Expire Weekly

• If your Google Cloud app is in Testing mode, refresh tokens expire after 7 days
• Consider moving your app to Production for longer-lived refresh tokens (requires Google verification)

Manual Authentication

For re-authentication or troubleshooting:

# For npx installations
export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/credentials.json"
npx @cocal/google-calendar-mcp auth

# For local installations
npm run auth

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "google-calendar" '{"command":"npx","args":["@cocal/google-calendar-mcp"],"env":{"GOOGLE_OAUTH_CREDENTIALS":"/path/to/your/gcp-oauth.keys.json"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "google-calendar": {
            "command": "npx",
            "args": [
                "@cocal/google-calendar-mcp"
            ],
            "env": {
                "GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "google-calendar": {
            "command": "npx",
            "args": [
                "@cocal/google-calendar-mcp"
            ],
            "env": {
                "GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect