google-calendar-mcp-server

Google Calendar MCP Server

A Model Context Protocol (MCP) server that provides access to Google Calendar.

Features

• List calendar events within a time range
• Get details of specific events
• Search events by text query
• Create new calendar events
• List all accessible calendars

Setup Instructions

1. Get Google Calendar API Credentials

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Calendar API:

• Navigate to "APIs & Services" > "Library"
• Search for "Google Calendar API"
• Click "Enable"

1. Create OAuth 2.0 credentials:

• Go to "APIs & Services" > "Credentials"
• Click "Create Credentials" > "OAuth client ID"
• Select "Desktop app" as the application type
• Download the credentials JSON file

1. Save the credentials file as ~/.config/google-calendar-mcp/credentials.json

2. Install Dependencies

pip install -r requirements.txt

3. Configure MCP

Add this to your MCP configuration file (usually ~/.config/mcp/config.json or similar):

{
  "mcpServers": {
    "google-calendar": {
      "command": "python",
      "args": ["/path/to/google-calendar-mcp/server.py"]
    }
  }
}

4. First Run - Authentication

On the first run, the server will:

1. Open a browser window for Google OAuth authentication
2. Ask you to grant calendar access permissions
3. Save the authentication token to ~/.config/google-calendar-mcp/token.json

Future runs will use the saved token automatically.

Docker Deployment

You can run the Google Calendar MCP Server in Docker for easier deployment and isolation. See DOCKER.md for comprehensive Docker setup instructions.

Quick Start:

1. Authenticate locally first (one-time): python server.py
2. Build and run: docker-compose build && docker-compose up -d
3. Configure your MCP client to use: docker exec -i google-calendar-mcp python -u server.py

See DOCKER.md for detailed instructions, troubleshooting, and advanced configurations.

Available Tools

list_events

List calendar events for a specified time range.

Parameters:

• time_min (optional): Start time in ISO format (defaults to now)
• time_max (optional): End time in ISO format (defaults to end of today)
• max_results (optional): Maximum number of events (default: 10, max: 250)
• calendar_id (optional): Calendar ID to query (default: 'primary')

Example: ``json { "time_min": "2026-01-22T00:00:00Z", "time_max": "2026-01-22T23:59:59Z", "max_results": 20 } ``

get_event

Get details of a specific calendar event.

Parameters:

• event_id (required): The event ID
• calendar_id (optional): Calendar ID (default: 'primary')

search_events

Search for calendar events by text query.

Parameters:

• query (required): Text to search for
• time_min (optional): Start time in ISO format
• time_max (optional): End time in ISO format
• max_results (optional): Maximum results (default: 10)

create_event

Create a new calendar event.

Parameters:

• summary (required): Event title
• start_time (required): Start time in ISO format
• end_time (required): End time in ISO format
• description (optional): Event description
• location (optional): Event location
• attendees (optional): Array of attendee email addresses
• calendar_id (optional): Calendar ID (default: 'primary')

Example: ``json { "summary": "Team Meeting", "start_time": "2026-01-23T10:00:00-06:00", "end_time": "2026-01-23T11:00:00-06:00", "description": "Weekly sync", "location": "Conference Room A", "attendees": ["colleague@example.com"] } ``

list_calendars

List all calendars accessible to the user.

No parameters required.

Time Format Notes

• All times should be in ISO 8601 format
• Include timezone offset for accuracy (e.g., -06:00 for Central Time)
• UTC times should end with 'Z' (e.g., 2026-01-22T17:00:00Z)

Troubleshooting

Authentication Issues

• Delete ~/.config/google-calendar-mcp/token.json and re-authenticate
• Verify credentials.json is valid and in the correct location
• Check that Google Calendar API is enabled in Google Cloud Console

Permission Errors

• Ensure the OAuth consent screen is configured
• Add test users if the app is in testing mode
• Verify the scopes include calendar access

Security Notes

• Never commit credentials.json or token.json to version control
• The token file contains refresh tokens that provide ongoing access
• Regularly review OAuth app permissions in Google Account settings