Google Calendar MCP server

This MCP server provides integration with Google Calendar, allowing LLMs to read, create, update, and search for calendar events through a standardized Model Context Protocol interface. It supports dynamic capabilities like adding events from images, analyzing calendars, checking attendance, and coordinating meetings.

Requirements

• Node.js (Latest LTS recommended)
• TypeScript 5.3 or higher
• A Google Cloud project with the 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 (optional):
     • 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 address as a test user under the OAuth Consent screen
   • Note: It takes a few minutes for test users to be added
   • Note: While in test mode, auth tokens expire after 1 week

Installation

1. Clone the repository
2. Install dependencies:

   npm install
   

3. Set up OAuth credentials:
   • Download your Google OAuth credentials from the 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 file and add your credentials:

     cp gcp-oauth.keys.example.json gcp-oauth.keys.json
     

Starting the Server

Start the MCP server with:

npm run start

Authentication

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

Automatic Authentication Flow

1. Ensure gcp-oauth.keys.json is correctly placed in the project root
2. Start the server with npm start
3. If no valid tokens exist:
   • A temporary local web server starts (on ports 3000-3004)
   • Your browser opens to the Google Account login screen
   • After authorization, you'll be redirected to a local success page
   • Tokens are saved to .gcp-saved-tokens.json
   • The temporary auth server shuts down and the MCP server starts

Manual Authentication

To re-authenticate:

npm run auth

Token Management

• Tokens are stored in .gcp-saved-tokens.json (do not commit this file)
• The server automatically refreshes expired access tokens
• If refresh tokens expire (after 7 days in test mode), you'll need to re-authenticate

Using 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"]
    }
  }
}

2. Replace <absolute-path-to-project-folder> with the actual path to your project directory
3. Restart Claude Desktop

Example Capabilities

Adding Events from Images

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

Supported formats: PNG, JPEG, GIF. Images can contain event details like date, time, location, and description.

Calendar Analysis

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

Checking Attendance

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

Auto Coordinating 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.

Providing 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 OAuth settings
• Try deleting .gcp-saved-tokens.json and re-authenticating
• Check that no other process is using ports 3000-3004

Token Expiration

• In Testing mode, refresh tokens expire after 7 days
• Consider moving your app to Production 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.