Google Calendar MCP Server Implementation

This artifact serves as a Model Context Protocol (MCP) backend, specifically designed to bridge AI models, such as Claude, with the robust functionality of the Google Calendar service.

Key Capabilities

• Multi-Source Aggregation: Consolidate and present scheduling data from numerous associated Google Calendars.
• Comprehensive Entry Lifecycle Management: Full CRUD operations (Create, Retrieve, Modify, Erase) for individual appointment records.
• Recurrence Handling: Sophisticated manipulation methods tailored for complex, repeating schedule items.
• Availability Assessment: Execute free/busy checks across a defined set of user calendars.
• Semantic Interpretation: Utilize natural language processing for accurate interpretation of temporal specifications (dates and times).
• Intelligent Ingestion: Parse and import event specifications directly from unstructured digital artifacts (e.g., visual media, documents, web URLs).

Initial Setup Prerequisites

1. Provisioning of a Google Cloud Platform (GCP) project.
2. Activation of the Google Calendar API within that project.
3. Generation of valid OAuth 2.0 authentication credentials (must be configured as a Desktop application type).

GCP Credential Configuration Steps

1. Navigate to the Google Cloud Console.
2. Select or initialize your target project.
3. Activate the Google Calendar API.
4. Define new OAuth 2.0 credentials:
5. Access 'Credentials' section and select 'Create Credentials' -> 'OAuth client ID'.
6. Specify 'User data' as the accessed data type.
7. Input application identification details.
8. Define necessary scopes (e.g., https://www.googleapis.com/auth/calendar.events and https://www.googleapis.com/auth/calendar).
9. Crucially, set the Application Type to "Desktop app".
10. Securely store the resulting authentication key file.
11. Add your operational email address as an authorized test user via the Audience screen.
    • Note: Propagation of test users may delay OAuth consent progression.
    • Test mode limitation: Tokens expire weekly, necessitating re-authorization (see below for resolution).

Deployment Options

Method A: Via npx (Recommended for quick integration)

Configure your host environment (e.g., Claude Desktop config file) as follows, ensuring the GOOGLE_OAUTH_CREDENTIALS points to your generated key file:

Configuration File Snippet (e.g., claude_desktop_config.json)

{ "mcpServers": { "google-calendar": { "command": "npx", "args": ["@cocal/google-calendar-mcp"], "env": { "GOOGLE_OAUTH_CREDENTIALS": "/absolute/path/to/your/gcp-oauth.keys.json" } } } }

Method B: Local Source Compilation

bash git clone https://github.com/nspady/google-calendar-mcp.git cd google-calendar-mcp npm install npm run build

Configuration requires pointing the environment variable to the credentials file.

Method C: Containerized Execution

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

Copy credentials into the working directory for Docker access

cp /path/to/your/gcp-oauth.keys.json . docker compose up

Initial Operationalization

1. Launch the client application (e.g., Claude Desktop).
2. The backend service will initiate an OAuth authorization sequence.
3. Complete the browser-based consent flow.
4. Calendar functionalities will become accessible.

Token Renewal Procedures

If operating under the default test mode, tokens require renewal every 7 days. Client applications usually automate this, but manual intervention may be needed for errors:

npx Re-auth Command: bash export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/gcp-oauth.keys.json" npx @cocal/google-calendar-mcp auth

Production Mode Transition (To eliminate weekly re-auths):

In the GCP Console, navigate to 'OAuth consent screen', select 'PUBLISH APP'. This bypasses the 7-day limit but results in users seeing an 'Unverified App' warning upon first connection.

Illustrative Use Cases

Beyond standard scheduling interactions, the interface supports complex, multi-stage task execution:

1. Coordinated Time Slot Determination:

Analyze availability across my 'Work' and 'Personal' calendars for the upcoming seven days. Identify a contiguous one-hour window suitable for a consultation with an individual based in London.

1. Data Extraction and Event Population:

Parse the attached image file and use the identified date, time, and location details to construct a new calendar entry.

1. Activity Anomaly Detection:

Generate a summary of all appointments scheduled this week that deviate significantly from my typical recurring schedule.

1. Invitation Acceptance Auditing:

For all events scheduled tomorrow, list attendees who have not yet confirmed their participation.

1. Automated Time Slot Validation:

I have received a set of proposed available time blocks: {available times}. Cross-reference this set against my current calendar state and confirm which proposed slots are genuinely free on my side.

Exposed Tool Registry

Tool Name	Functionality Description
list-calendars	Retrieves a manifest of all accessible calendar identifiers.
list-events	Fetches scheduled entries subject to temporal bounds filtering.
search-events	Executes full-text searches across event summaries and details.
create-event	Inserts novel entries into the specified calendar.
update-event	Modifies properties of an existing calendar event record.
delete-event	Permanently removes a scheduled item.
get-freebusy	Queries temporal occupancy status, accommodating external calendar overlays.
list-colors	Provides the enumeration of valid color codes mappable to event entries.

Configuration & Environment Variables

• GOOGLE_OAUTH_CREDENTIALS: Path to the essential GCP JSON credentials file.
• GOOGLE_CALENDAR_MCP_TOKEN_PATH: Optional setting to override the default location for persisted authentication tokens.

Operational Security Posture

• Authentication tokens are persisted locally within secure system directories.
• Sensitive credential material remains confined to the local execution environment.
• All external API interactions are contingent upon prior, explicit user authorization grants.

Troubleshooting Common Failures

1. Missing Credentials File: Users leveraging npx must explicitly define the file location via the GOOGLE_OAUTH_CREDENTIALS environment variable.
2. Authentication Flow Issues: Confirm the GCP credentials object is typed as a 'Desktop App' and verify the test user list is correctly populated and synchronized.
3. Browser Authentication Hangs: Attempting the manual authentication process described below, utilizing a Chromium-based browser implementation for the OAuth redirect, is often necessary for test mode flows.