MCP Google Calendar: AI Automation & Workflow Optimization

Key Features of MCP Google Calendar

• AI-powered command parsing for natural language instructions
• WebSocket-based real-time event synchronization
• Fallback mechanisms for API errors and connection drops
• Multi-port support to avoid configuration conflicts
• Granular error logging and diagnostic capabilities
• OAuth2 authentication framework with security best practices

Use Cases for AI-Driven Calendar Management

MCP Google Calendar

A Model Context Protocol (MCP) server for Google Calendar integration with Claude and other AI assistants.

Overview

This MCP server allows AI assistants like Claude to interact with Google Calendar, enabling seamless calendar management through natural language conversations.

Features

• View upcoming events and meetings
• Create new calendar events
• Update existing events
• Delete events
• Search for events by time range, keywords, or participants
• Get free/busy times for scheduling
• List available calendars
• Set up meeting invitations with attendees

Installation

# Install globally
npm install -g @takumi0706/mcp-google-calendar

# Running directly without npx (recommended)
node -e "require('child_process').spawn('node', [require.resolve('@takumi0706/mcp-google-calendar/claude_desktop_launcher.js')], {stdio: 'inherit'}).on('exit', (code) => process.exit(code || 0));"

Configuration

Google API Setup

1. Create a project in the Google Cloud Console
2. Enable the Google Calendar API
3. Create OAuth 2.0 credentials (web application)
4. Set up authorized redirect URIs (default: http://localhost:3000/oauth2callback)
5. Download credentials as JSON file

Environment Setup

Create a .env file or set environment variables:

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback
MCP_PORT=3000

Alternatively, you can use the provided .env.example as a template:

cp .env.example .env
# Edit .env with your credentials

Claude Desktop Setup

Add the following to your Claude Desktop configuration (usually located at ~/.config/claude-desktop/config.json):

{
  "mcpServers": {
    "googleCalendar": {
      "command": "node",
      "args": [
        "-e",
        "require('child_process').spawn('node', [require.resolve('@takumi0706/mcp-google-calendar/claude_desktop_launcher.js')], {stdio: 'inherit', env: process.env}).on('exit', (code) => process.exit(code || 0));"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "<YOUR_CLIENT_ID>",
        "GOOGLE_CLIENT_SECRET": "<YOUR_CLIENT_SECRET>",
        "MCP_PORT": "3000"
      }
    }
  }
}

Important Notes:

• As of version 1.0.7, we've completely redesigned the launcher to avoid permission issues
• The new launcher directly handles installation and execution without relying on npx
• The launcher will automatically update to the latest version each time it starts
• Compatible with Node.js 16.x and above

A template configuration file is provided as claude_desktop_config.example.json.

First Run and Authentication

On first run, the MCP server will launch a web browser for OAuth authentication:

1. Start the MCP server through one of the recommended methods
2. A browser window will open asking you to authorize access to your Google Calendar
3. After authorization, you'll be redirected back to the MCP server
4. The server will save the refresh token for future use

Troubleshooting

Common Issues

Permission Denied Errors

If you see "Permission denied" errors:

1. Use the built-in launcher which doesn't rely on executable permissions:

   node -e "require('child_process').spawn('node', [require.resolve('@takumi0706/mcp-google-calendar/claude_desktop_launcher.js')], {stdio: 'inherit'}).on('exit', (code) => process.exit(code || 0));"

2. Or manually fix permissions:

   chmod +x $(npm root -g)/@takumi0706/mcp-google-calendar/dist/cli.js

chmod +x $(npm root -g)/@takumi0706/mcp-google-calendar/claude_desktop_launcher.js

3. For Claude Desktop, make sure to use the updated configuration example.

Connection Timeout Errors

If you see timeout errors with Claude Desktop:

1. Make sure you're using the recommended Claude Desktop configuration with the direct node execution method

2. Kill any running instances:

   pkill -f mcp-google-calendar

3. Restart Claude Desktop completely

Authentication Issues

If you have trouble authenticating, try clearing the stored token:

rm ~/.mcp-google-calendar/token.json

Debug Mode

For advanced troubleshooting, you can run in debug mode:

DEBUG=true node -e "require('child_process').spawn('node', [require.resolve('@takumi0706/mcp-google-calendar/claude_desktop_launcher.js')], {stdio: 'inherit', env: {...process.env, DEBUG: 'true'}}).on('exit', (code) => process.exit(code || 0));"

Available MCP Functions

This MCP server exposes the following functions:

Function Name	Description
getStatus	Check if the server is ready to handle requests
listCalendars	List all available calendars
getEvent	Get details of a specific event
listEvents	List events within a time range
searchEvents	Search for events by keyword
createEvent	Create a new calendar event
updateEvent	Update an existing event
deleteEvent	Delete an event
getUpcomingEvents	Get all upcoming events
getTodayEvents	Get events for today
getWeekEvents	Get events for the current week
getMonthEvents	Get events for the current month
getFreeBusy	Check free/busy status for a time range

Example Commands for Claude

• "Show my calendar events for today"
• "Schedule a meeting with John tomorrow at 3 PM for 1 hour"
• "Find free time in my calendar next week"
• "Cancel my 2 PM meeting today"
• "Update the location of my Friday meeting to Conference Room B"
• "Show me all my meetings about 'Project X'"
• "List all my calendars"
• "Create a weekly recurring meeting every Monday at 9 AM"
• "Find events where Sarah is attending"
• "Move my 4 PM meeting to 5 PM"

Development

To set up the development environment:

# Clone the repository
git clone https://github.com/takumi0706/mcp-google-calendar.git
cd mcp-google-calendar

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your credentials

# Start the development server
npm run dev

Building

npm run build

Changelog

v1.0.7 (2025-03-17)

• Fixed "Permission denied" errors with completely new launcher approach
• Fixed CI build process issues and added Node.js 16 compatibility
• Created standalone launcher script that doesn't rely on executable permissions
• Added direct node execution method for Claude Desktop integration
• Added explicit permission setting in npm scripts
• Updated documentation with improved troubleshooting steps

v1.0.6 (2025-03-17)

• Fixed npm ENOTEMPTY errors with a custom install helper script
• Fixed MCP connection timeouts by adding WebSocket ping/pong mechanism
• Updated Claude Desktop configuration example with a direct node execution method
• Improved WebSocket connection stability with better error handling
• Enhanced error messages and logging for easier troubleshooting

v1.0.5 (2025-03-17)

• Fixed JSON parsing errors by switching to direct stderr output
• Added automatic port selection when default port is in use
• Improved error handling for server startup issues
• Added support for dynamic redirect URIs in the OAuth flow
• Updated logging to avoid WebSocket connection issues

v1.0.4 (2025-03-17)

• Completely remove formatted text in banner to prevent any JSON parsing errors
• Add troubleshooting section to README with common issues
• Improve port conflict handling with Claude Desktop
• Add more explicit warning about port 9876 conflicts

v1.0.3 (2025-03-17)

• Fix port conflict errors when multiple instances try to start simultaneously
• Fix JSON parsing errors with box drawing characters in console output
• Add better error handling for WebSocket connections
• Add explicit error handling for port binding issues
• Update Claude Desktop configuration example to include port setting

v1.0.2 (2025-03-17)

• Fix token storage location to use user home directory
• Add error handling and fallback to temp directory if home directory is not writable

v1.0.1 (2025-03-17)

• Initial release with fixes

v1.0.0 (2025-03-17)

• Initial release

License

MIT