Skip to main content

​
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

  1. Go to the Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the Google Calendar API
  4. Go to Credentials → Create Credentials → OAuth client ID
  5. Select Desktop app as the application type
  6. Download the credentials JSON file
  7. 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:
ToolDescription
list_eventsList events in a time range
create_eventCreate a new calendar event
update_eventUpdate an existing event
delete_eventDelete an event
get_freebusyCheck 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.