Google Calendar

Google Calendar MCP Server

What is Google Calendar MCP Server?

This project is an MCP (Model Context Protocol) server that enables Claude (an AI assistant, likely referring to the Claude Desktop App) to interact with your Google Calendar. It acts as a bridge, allowing Claude to perform various calendar-related tasks on your behalf.

How to use Google Calendar MCP Server?

Using the Google Calendar MCP Server involves several setup steps:

1. Prerequisites: Ensure you have Node.js (v16+), the Claude Desktop App, a Google Cloud Project, enabled Google Calendar API, and OAuth 2.0 credentials.
2. Google Cloud Project Setup: Create or select a Google Cloud Project and enable the Google Calendar API.
3. OAuth Consent Screen Configuration: Configure the OAuth consent screen in Google Cloud, specifying user type, app information, and adding necessary scopes (https://www.googleapis.com/auth/calendar, https://www.googleapis.com/auth/calendar.events).
4. OAuth 2.0 Credentials Creation: Create OAuth client ID credentials for a desktop app and download the client configuration file.
5. Get Refresh Token: Use a provided Node.js script (getToken.js) to obtain a refresh token. This involves running the script, opening a generated URL in your browser, authenticating with Google, and copying the refresh token displayed in the console.
6. Claude Desktop Configuration: Configure your Claude Desktop App by adding the google-calendar MCP server entry to its configuration file (claude_desktop_config.json). This involves setting the command, arguments, and environment variables (client ID, client secret, redirect URI, and refresh token).
7. Initial Project Setup: Create a new directory, initialize an npm project, install dependencies (@modelcontextprotocol/sdk, googleapis, google-auth-library, zod, typescript), create a tsconfig.json file, update package.json scripts, and create a .env file for local development.
8. Building and Running: Build the server using npm run build. The server will automatically start when you open the Claude Desktop App.

Key Features of Google Calendar MCP Server

• Calendar Event Management: List, create, update, and delete calendar events.
• Free Time Finding: Identify available time slots in your Google Calendar.
• Integration with Claude: Seamlessly integrates with the Claude Desktop App, allowing natural language commands for calendar interactions.
• Secure Authentication: Utilizes OAuth 2.0 for secure access to Google Calendar data.

Use Cases of Google Calendar MCP Server

• Scheduling Meetings: Quickly schedule meetings with specified participants and durations.
• Managing Appointments: Easily add, modify, or cancel appointments.
• Checking Availability: Find free time slots for personal or professional use.
• Event Reminders: Potentially set up reminders for upcoming events (though not explicitly stated, it's a common calendar function).
• Automated Calendar Tasks: Automate routine calendar management tasks through Claude's conversational interface.

FAQ from Google Calendar MCP Server

Q: Tools not appearing in Claude? A: Check Claude Desktop logs (tail -f ~/Library/Logs/Claude/mcp*.log), verify environment variables, and ensure the absolute path to index.js is correct.

Q: Authentication Errors? A: Verify OAuth credentials, check refresh token validity, and ensure required scopes are enabled.

Q: Server Connection Issues? A: Check if the server built successfully, verify file permissions on build/index.js (should be 755), and try running the server directly (node /path/to/build/index.js).

Q: How to view server logs? A: Use tail -n 20 -f ~/Library/Logs/Claude/mcp*.log for MacOS/Linux or Get-Content -Path "$env:AppData\Claude\Logs\mcp*.log" -Wait -Tail 20 for Windows.

Q: What are the important environment variables? A: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI (should be http://localhost), and GOOGLE_REFRESH_TOKEN (a long string that doesn't expire).

Q: What are the security considerations? A: Keep OAuth credentials secure, do not commit them to version control, use environment variables for sensitive data, regularly rotate refresh tokens, and monitor API usage in Google Cloud Console.

Google Calendar MCP Server

This MCP server allows Claude to interact with your Google Calendar, enabling capabilities like listing events, creating meetings, and finding free time slots.

Prerequisites

• Node.js (v16 or higher)
• Claude Desktop App
• A Google Cloud Project
• Google Calendar API enabled
• OAuth 2.0 credentials

Setup Instructions

1. Create a Google Cloud Project

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Calendar API:
   • Go to "APIs & Services" > "Library"
   • Search for "Google Calendar API"
   • Click "Enable"

2. Configure OAuth Consent Screen

1. Go to "APIs & Services" > "OAuth consent screen"
2. Select "External" user type (unless you have a Google Workspace organization)
3. Fill in the required information:
   • App name
   • User support email
   • Developer contact information
4. Add the following scopes:
   • https://www.googleapis.com/auth/calendar
   • https://www.googleapis.com/auth/calendar.events
5. Add your email address as a test user

3. Create OAuth 2.0 Credentials

1. Go to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "OAuth client ID"
3. Select "Desktop app" as the application type
4. Name your client (e.g., "MCP Calendar Client")
5. Click "Create"
6. Download the client configuration file (you'll need the client ID and client secret)

4. Get Refresh Token

1. Create a new file named getToken.js:

const { google } = require('googleapis');
const http = require('http');
const url = require('url');

// Replace these with your OAuth 2.0 credentials
const CLIENT_ID = 'your-client-id';
const CLIENT_SECRET = 'your-client-secret';
const REDIRECT_URI = 'http://localhost:3000/oauth2callback';

// Configure OAuth2 client
const oauth2Client = new google.auth.OAuth2(
  CLIENT_ID,
  CLIENT_SECRET,
  REDIRECT_URI
);

// Define scopes
const scopes = [
  'https://www.googleapis.com/auth/calendar',
  'https://www.googleapis.com/auth/calendar.events'
];

async function getRefreshToken() {
  return new Promise((resolve, reject) => {
    try {
      // Create server to handle OAuth callback
      const server = http.createServer(async (req, res) => {
        try {
          const queryParams = url.parse(req.url, true).query;
          
          if (queryParams.code) {
            // Get tokens from code
            const { tokens } = await oauth2Client.getToken(queryParams.code);
            console.log('\n=================');
            console.log('Refresh Token:', tokens.refresh_token);
            console.log('=================\n');
            console.log('Save this refresh token in your configuration!');
            
            // Send success response
            res.end('Authentication successful! You can close this window.');
            
            // Close server
            server.close();
            resolve(tokens);
          }
        } catch (error) {
          console.error('Error getting tokens:', error);
          res.end('Authentication failed! Please check console for errors.');
          reject(error);
        }
      }).listen(3000, () => {
        // Generate auth url
        const authUrl = oauth2Client.generateAuthUrl({
          access_type: 'offline',
          scope: scopes,
          prompt: 'consent'  // Force consent screen to ensure refresh token
        });

        console.log('1. Copy this URL and paste it in your browser:');
        console.log('\n', authUrl, '\n');
        console.log('2. Follow the Google authentication process');
        console.log('3. Wait for the refresh token to appear here');
      });

    } catch (error) {
      console.error('Server creation error:', error);
      reject(error);
    }
  });
}

// Run the token retrieval
getRefreshToken().catch(console.error);

2. Install required dependency:

npm install googleapis

3. Update the script with your OAuth credentials:

   • Replace your-client-id with your actual client ID
   • Replace your-client-secret with your actual client secret

4. Run the script:

node getToken.js

5. Follow the instructions in the console:
   • Copy the provided URL
   • Paste it into your browser
   • Complete the Google authentication process
   • Copy the refresh token that appears in the console

5. Configure Claude Desktop

1. Open your Claude Desktop configuration file:

For MacOS:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

For Windows:

code %AppData%\Claude\claude_desktop_config.json

2. Add or update the configuration:

{
    "mcpServers": {
        "google-calendar": {
            "command": "node",
            "args": [
                "/ABSOLUTE/PATH/TO/YOUR/build/index.js"
            ],
            "env": {
                "GOOGLE_CLIENT_ID": "your_client_id_here",
                "GOOGLE_CLIENT_SECRET": "your_client_secret_here",
                "GOOGLE_REDIRECT_URI": "http://localhost",
                "GOOGLE_REFRESH_TOKEN": "your_refresh_token_here"
            }
        }
    }
}

3. Save the file and restart Claude Desktop

Initial Project Setup

1. Create a new directory for your project:

mkdir google-calendar-mcp
cd google-calendar-mcp

2. Initialize a new npm project:

npm init -y

3. Install dependencies:

npm install @modelcontextprotocol/sdk googleapis google-auth-library zod
npm install -D @types/node typescript

4. Create a tsconfig.json file:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

5. Update package.json:

{
  "type": "module",
  "scripts": {
    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\""
  }
}

6. Create your source directory:

mkdir src

7. Create a .env file for local development (don't commit this file):

GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REDIRECT_URI=http://localhost
GOOGLE_REFRESH_TOKEN=your_refresh_token_here

Building and Running

1. Build the server:

npm run build

2. The server will automatically start when you open Claude Desktop

Available Tools

The server provides the following tools:

1. list_events: List calendar events within a specified time range
2. create_event: Create a new calendar event
3. update_event: Update an existing calendar event
4. delete_event: Delete a calendar event
5. find_free_time: Find available time slots in the calendar

Example Usage in Claude

After setup, you can use commands like:

• "Show me my calendar events for next week"
• "Schedule a meeting with [email_id] tomorrow at 2 PM for 1 hour"
• "Find a free 30-minute slot this afternoon"
• "Update my 3 PM meeting to 4 PM"
• "Cancel my meeting with ID [event_id]"

Troubleshooting

Common Issues

1. Tools not appearing in Claude:

   • Check Claude Desktop logs: tail -f ~/Library/Logs/Claude/mcp*.log
   • Verify all environment variables are set correctly
   • Ensure the path to index.js is absolute and correct

2. Authentication Errors:

   • Verify your OAuth credentials are correct
   • Check if refresh token is valid
   • Ensure required scopes are enabled

3. Server Connection Issues:

   • Check if the server built successfully
   • Verify file permissions on build/index.js (should be 755)
   • Try running the server directly: node /path/to/build/index.js

Viewing Logs

To view server logs:

# For MacOS/Linux:
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# For Windows:
Get-Content -Path "$env:AppData\Claude\Logs\mcp*.log" -Wait -Tail 20

Environment Variables

If you're getting environment variable errors, verify each one:

1. GOOGLE_CLIENT_ID: Should start with something like "123456789-..."
2. GOOGLE_CLIENT_SECRET: Usually ends in ".apps.googleusercontent.com"
3. GOOGLE_REDIRECT_URI: Should be "http://localhost"
4. GOOGLE_REFRESH_TOKEN: A long string that doesn't expire

Security Considerations

• Keep your OAuth credentials secure
• Don't commit credentials to version control
• Use environment variables for sensitive data
• Regularly rotate refresh tokens
• Monitor API usage in Google Cloud Console

License

MIT License - See LICENSE file for details.

Support

If you encounter any issues:

1. Check the troubleshooting section above
2. Review Claude Desktop logs
3. Open an issue on GitHub
4. Contact the maintainer