Google Calendar MCP server

Google Calendar MCP Server is a Model Context Protocol (MCP) server that integrates with Google Calendar, enabling Large Language Models to read, create, update, and search calendar events through a standardized interface. It allows dynamic interactions with your Google Calendar including adding events from screenshots, analyzing your schedule, checking attendance, and coordinating availability.

Installation Requirements

• Node.js (Latest LTS recommended)
• TypeScript 5.3 or higher
• A Google Cloud project with Calendar API enabled
• OAuth 2.0 credentials (Client ID and Client Secret)

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 scopes: https://www.googleapis.com/auth/calendar.events (or broader https://www.googleapis.com/auth/calendar)
   • Select "Desktop app" as the application type
   • Add your email as a test user under the OAuth Consent screen
   • Note: It takes a few minutes for test users to propagate
   • Note: In test mode, auth tokens expire after 1 week

Installation Steps

1. Clone the repository
2. Install dependencies:

   npm install
   

3. Set up OAuth credentials:
   • Download your Google OAuth credentials from Google Cloud Console
   • Rename the file to gcp-oauth.keys.json and place it in the project root
   • Ensure the file contains credentials for a "Desktop app"
   • Alternatively, copy the template: cp gcp-oauth.keys.example.json gcp-oauth.keys.json and add your credentials

Authentication

The server handles Google OAuth 2.0 authentication to access your calendar data.

Automatic Authentication Flow

1. Ensure gcp-oauth.keys.json is in the project root
2. Start the MCP server:

   npm start
   

3. The server checks for existing valid tokens in .gcp-saved-tokens.json
4. If no valid tokens are found:
   • A temporary local web server starts (on ports 3000-3004)
   • Your browser opens to the Google Account login screen
   • After authorization, you're redirected to a local success page
   • Tokens are saved to .gcp-saved-tokens.json
   • The MCP server continues startup

Manual Authentication

To re-authenticate:

npm run auth

Token Management

• Tokens are stored in .gcp-saved-tokens.json (not committed to version control)
• The server automatically refreshes expired access tokens
• If the refresh token expires (after 7 days in test mode), re-authenticate

Usage with Claude Desktop

1. Add this configuration to your Claude Desktop config file (e.g., /Users/<user>/Library/Application Support/Claude/claude_desktop_config.json):

   {
     "mcpServers": {
       "google-calendar": {
         "command": "node",
         "args": ["<absolute-path-to-project-folder>/build/index.js"]
       }
     }
   }
   

   Replace <absolute-path-to-project-folder> with your actual project path

2. Restart Claude Desktop

Example Capabilities

The MCP server enables the following interactions:

Add Events from Images

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

Supports PNG, JPEG, and GIF images containing event details

Calendar Analysis

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

Check Attendance

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

Auto Coordinate Events

Here's some available that was provided to me by someone.
Take a look at the available times and create an event that is free on my work calendar.

Provide Availability

Please provide availability looking at both my personal and work calendar for this upcoming week.
Choose times that work well for normal working hours on the East Coast. Meeting time is 1 hour

Troubleshooting

Authentication Errors

• Ensure gcp-oauth.keys.json contains Desktop App credentials
• Verify your email is added as a Test User in Google Cloud
• Try deleting .gcp-saved-tokens.json and re-authenticate
• Check that ports 3000-3004 are available

Token Expiration

• In test mode, refresh tokens expire after 7 days
• Consider moving to Production mode for longer-lived tokens

Build Issues

• Run npm install again
• Check Node.js version (use LTS)
• Delete the build/ directory and run npm run build

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.