Google Calendar MCP Server

Overview

The Google Calendar integration enables AI assistants to interact with your Google Calendar, providing capabilities to manage events, check availability, analyze scheduling patterns, and more.

Setup Requirements

Before installing the Google Calendar integration, you'll need:

1. Node.js (Latest LTS version recommended)
2. A Google Cloud project with the Calendar API enabled
3. OAuth 2.0 credentials (Client ID and Client Secret)

Google Cloud Setup

1. Go to the Google Cloud Console (https://console.cloud.google.com/)
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:
   • Navigate to "Credentials" in the sidebar
   • 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 (or https://www.googleapis.com/auth/calendar.events for more limited access)
   • Select "Desktop app" as the application type
   • Add your email address as a test user under the OAuth Consent screen

Note: While your app is in test mode, auth tokens will expire after 1 week and need to be refreshed.

Installation

1. Clone the repository:

git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp

2. Install dependencies:

npm install

3. Download your Google OAuth credentials from the Google Cloud Console and save them as gcp-oauth.keys.json in the project root directory.

Alternatively, copy the example file and add your credentials:

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

4. Build the project:

npm run build

Authentication

The integration handles Google OAuth 2.0 authentication to access your calendar data:

1. Start the server with npm start
2. If no valid tokens exist, your browser will open to the Google Account login
3. Follow the prompts to authorize the application
4. Upon successful authorization, tokens will be saved to .gcp-saved-tokens.json

To manually re-authenticate at any time, run:

npm run auth

Configuration with Claude Desktop

Add this configuration to your Claude Desktop config file (typically located at /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 the actual path to your project directory.

After adding the configuration, restart Claude Desktop.

Usage Examples

Once configured, you can interact with your Google Calendar using natural language:

• Create events: "Schedule a meeting with the design team tomorrow at 2pm for 1 hour"
• Check availability: "When am I free next Tuesday afternoon?"
• Add events from images: "Add this event to my calendar based on the attached screenshot"
• Calendar analysis: "What events do I have this week that aren't part of my usual routine?"
• Check attendance: "Which events tomorrow have attendees who haven't accepted?"
• Coordinate availability: "Find a time that works for both my personal and work calendars next week during East Coast business hours"

Troubleshooting

• Authentication Errors: Ensure gcp-oauth.keys.json exists and contains credentials for a Desktop App type
• Token Expiration: If using a test app in Google Cloud, tokens expire after 7 days and require re-authentication with npm run auth
• Port Conflicts: The authentication server tries ports 3000-3004; ensure one of these is available during authentication

Security Notes

• OAuth credentials and saved tokens should never be committed to version control
• The server runs locally and requires OAuth authentication for security
• For production use, consider getting your OAuth application verified by Google