Google Calendar MCP Agent

Overview

Build an autonomous agent that connects to Google Calendar, analyzes your schedule, and generates time-use reports — meeting load analysis, free slot summaries, and weekly schedule exports.

This example uses @cocal/google-calendar-mcp, a community-maintained MCP server — not an official Google product. Review the package source and permissions before granting access to your calendar data.

Prerequisites

A Google Cloud project with the Calendar API enabled
OAuth 2.0 credentials (Desktop app type) downloaded as a JSON file
Node.js installed (for npx)

Setup

1. Create OAuth Credentials

Go to the Google Cloud Console
Create a new project or select an existing one
Enable the Google Calendar API
Go to Credentials → Create Credentials → OAuth client ID
Select Desktop app as the application type
Download the credentials JSON file
Add your email as a test user under the Audience screen

2. Place the Credentials File

Save the downloaded OAuth credentials JSON file to a known path, for example:

mkdir -p ~/.config/google-calendar-mcp
cp /path/to/downloaded-credentials.json ~/.config/google-calendar-mcp/credentials.json

3. Authenticate

Run the authentication flow to generate access tokens:

export GOOGLE_OAUTH_CREDENTIALS="$HOME/.config/google-calendar-mcp/credentials.json"
npx @cocal/google-calendar-mcp auth

This opens a browser window where you log in to Google and grant calendar access. The resulting auth tokens are saved automatically.

If your Google Cloud app is in test mode (the default), OAuth tokens expire after 7 days. You will need to re-run the auth command weekly.

4. Environment Variables

# .env
ANTHROPIC_API_KEY=your-anthropic-key-here

Installation

# With uv (recommended)
uv pip install upsonic python-dotenv

# With pip
pip install upsonic python-dotenv

Example: Weekly Time-Use Report

The agent fetches all events for the current week and generates a time-use breakdown report.

import os
from dotenv import load_dotenv
from upsonic import AutonomousAgent, Task
from upsonic.tools.mcp import MCPHandler

load_dotenv()

calendar_handler = MCPHandler(
    command="npx -y @cocal/google-calendar-mcp",
    env={
        "GOOGLE_OAUTH_CREDENTIALS": os.path.expanduser(
            "~/.config/google-calendar-mcp/credentials.json"
        )
    },
    timeout_seconds=60
)

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-6",
    workspace="./calendar-reports",
    tools=[calendar_handler]
)

task = Task(
    description="""
    Analyze my calendar for the current week (Monday to Friday).

    1. Fetch all events for each day
    2. Categorize each event as: meeting, focus_time, 1on1, external, or other
    3. Calculate hours spent in each category per day

    Write the following files:
    - 'weekly_schedule.csv' with columns: date, event_title, start_time,
      end_time, duration_minutes, category, attendee_count
    - 'time_use_report.md' with:
      * Daily breakdown table (hours per category per day)
      * Total meeting hours vs available focus time
      * Busiest and lightest days
      * Back-to-back meeting chains (3+ consecutive meetings)
      * Recommendations for better time management
    """
)

agent.print_do(task)

Example: Availability Finder

The agent analyzes your calendar and generates a free-slots document you can share with others for scheduling.

import os
from dotenv import load_dotenv
from upsonic import AutonomousAgent, Task
from upsonic.tools.mcp import MCPHandler

load_dotenv()

calendar_handler = MCPHandler(
    command="npx -y @cocal/google-calendar-mcp",
    env={
        "GOOGLE_OAUTH_CREDENTIALS": os.path.expanduser(
            "~/.config/google-calendar-mcp/credentials.json"
        )
    },
    timeout_seconds=60
)

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-6",
    workspace="./calendar-reports",
    tools=[calendar_handler]
)

task = Task(
    description="""
    Check my calendar for the next 5 business days and find all available
    slots for a 45-minute meeting.

    Constraints:
    - Only between 9:00 AM and 5:00 PM
    - Exclude 12:00 PM - 1:00 PM (lunch)
    - Require at least 15 minutes buffer between meetings

    Write 'available_slots.md' with:
    - A clean, shareable list of available time slots grouped by day
    - Total number of available slots
    - A note about the timezone
    """
)

agent.print_do(task)

Available Tools

Google Calendar MCP servers typically expose tools including:

Tool	Description
`list_events`	List events in a time range
`create_event`	Create a new calendar event
`update_event`	Update an existing event
`delete_event`	Delete an event
`get_freebusy`	Check free/busy status

Security Notes

Use OAuth 2.0 with the minimum required scopes (calendar.events, calendar.readonly).
Never commit your OAuth credentials JSON or token files to version control.
Auth tokens grant access to your calendar — treat them like passwords.
If your app is in test mode, tokens expire after 7 days. Re-run npx @cocal/google-calendar-mcp auth to re-authenticate.

GET STARTED

CONCEPTS

STARTING AN AGENT PROJECT

READY TO USE SNIPPETS

DEPLOYMENT

FURTHER READINGS

Google Calendar MCP Agent

Overview

Prerequisites

Setup

1. Create OAuth Credentials

2. Place the Credentials File

3. Authenticate

4. Environment Variables

Installation

Example: Weekly Time-Use Report

Example: Availability Finder

Available Tools

Security Notes

​Overview

​Prerequisites

​Setup

​1. Create OAuth Credentials

​2. Place the Credentials File

​3. Authenticate

​4. Environment Variables

​Installation

​Example: Weekly Time-Use Report

​Example: Availability Finder

​Available Tools

​Security Notes

Overview

Prerequisites

Setup

1. Create OAuth Credentials

2. Place the Credentials File

3. Authenticate

4. Environment Variables

Installation

Example: Weekly Time-Use Report

Example: Availability Finder

Available Tools

Security Notes