Google Calendar MCP server

The Google Calendar MCP Server enables LLMs to interact with Google Calendar through a standardized Model Context Protocol interface. It allows you to list, create, update, and delete calendar events, as well as process events from images.

Requirements

• Node.js 16 or higher
• 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 the scope: https://www.googleapis.com/auth/calendar.events (optional)
   • Select "Desktop app" as the application type
   • Add your email address as a test user under the OAuth Consent screen
     • Note: It will take a few minutes for the test user to be added

Installation

1. Clone the repository
2. Install dependencies:

   npm install
   

3. Build the TypeScript code:

   npm run build
   

4. Download your Google OAuth credentials from the Google Cloud Console (under "Credentials"), rename the file to gcp-oauth.keys.json, and place it in the root directory of the project

Authentication

The server supports both automatic and manual authentication flows:

Automatic Authentication (Recommended)

1. Place your Google OAuth credentials in a file named gcp-oauth.keys.json in the root directory
2. Start the MCP server:

   npm start
   

3. If no valid authentication tokens are found, the server will automatically:
   • Start an authentication server (on ports 3000-3004)
   • Open a browser window for the OAuth flow
   • Save the tokens securely once authenticated
   • Shut down the auth server
   • Continue normal MCP server operation

The server automatically manages token refresh and re-authentication when needed.

Manual Authentication

For advanced users or troubleshooting:

npm run auth

This will start the authentication server, open a browser window for the OAuth flow, save the tokens, and exit.

Usage

The server exposes the following tools:

• list-calendars: List all available calendars
• list-events: List events from a calendar
• create-event: Create a new calendar event
• update-event: Update an existing calendar event
• delete-event: Delete a calendar event

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": ["path/to/build/index.js"]
       }
     }
   }
   

2. Restart Claude Desktop

Example Usage

Beyond basic calendar operations, you can use more dynamic features:

Add Events from Screenshots and Images

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

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

Check Attendance

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

Auto Coordinate Events

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

Provide Your Own 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

Common issues and solutions:

1. OAuth Token expires after one week (7 days)

   • Apps in testing mode will need to go through the OAuth flow again after a week

2. OAuth Token Errors

   • Ensure your gcp-oauth.keys.json is correctly formatted
   • Try deleting .gcp-saved-tokens.json and re-authenticating

3. Image Processing Issues

   • Verify the image format is supported
   • Ensure the image contains clear, readable text

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.