Google Calendar Setup

Google Calendar is the mandatory integration for Morning Brain Starter. The tool reads your daily schedule, identifies meetings with clients, and helps you prepare context for each call.

Recommendation: Create a dedicated Google Cloud project named “morning-brain-starter” to keep these credentials and APIs separate from other projects.

Overview

Setting up Google Calendar integration requires:

Creating a Google Cloud project
Enabling required Google APIs
Creating OAuth 2.0 credentials
Running the OAuth setup script to generate a refresh token
Configuring which calendars to monitor

Prerequisites

A Google account with access to Google Cloud Console
Python 3.x installed with virtual environment activated
Morning Brain Starter project cloned locally

Step 1: Create Google Cloud Project

Navigate to Google Cloud Console

Go to Google Cloud Console and sign in with your Google account.

Create new project

Click the project dropdown at the top and select New Project.

Project name: morning-brain-starter
Organization: (leave as default or select your organization)
Click Create

Select the new project

After creation, ensure your new project is selected in the project dropdown.

Step 2: Enable Google APIs

Navigate to APIs & Services

In the Google Cloud Console:

Open the navigation menu (☰)
Go to APIs & Services → Library

Enable Google Calendar API (Required)

Search for “Google Calendar API”
Click on it
Click Enable

This API is required for Morning Brain Starter to function.

Enable Gmail API (Optional)

Search for “Gmail API”
Click on it
Click Enable

Only needed if you want to read recent emails in your morning briefing.

Enable Google Docs API (Optional)

Search for “Google Docs API”
Click on it
Click Enable

Needed if you want to read meeting transcriptions stored in Google Docs that are linked from calendar events.

Enable Google Meet API (Optional)

Search for “Google Meet API” or “Google Meet Spaces API”
Click on it
Click Enable

Needed if you want to programmatically enable transcription for Google Meet calls.

The OAuth setup script (setup_oauth.py) requests all scopes in a single authorization flow, so you can enable all APIs now even if you’re not using them yet.

Step 3: Create OAuth 2.0 Credentials

Navigate to Credentials

In Google Cloud Console:

Go to APIs & Services → Credentials

Configure OAuth consent screen

If this is your first time creating credentials:

Click Configure Consent Screen
Choose External (unless you’re using a Google Workspace account)
Fill in required fields:
- App name: Morning Brain Starter
- User support email: Your email
- Developer contact email: Your email
Click Save and Continue
Skip adding scopes (the script handles this)
Add yourself as a test user if using External user type
Click Save and Continue

Create OAuth Client ID

Click Create Credentials → OAuth client ID
Application type: Desktop app
Name: morning-brain-starter-desktop
Click Create

Download credentials

After creation, you’ll see a dialog with your client ID and client secret:

Copy the Client ID
Copy the Client Secret

You can also download the JSON file, but you’ll need to extract these values manually.

Keep your Client ID and Client Secret secure. Never commit them to version control or share them publicly.

Step 4: Configure Environment Variables

Create .env file

Copy the example environment file:

mkdir -p resources/secrets
cp .env.example resources/secrets/.env

Add Google credentials

Edit resources/secrets/.env and add your Google OAuth credentials:

# Obligatorio: Google Calendar
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REFRESH_TOKEN=

Leave GOOGLE_REFRESH_TOKEN empty for now - the setup script will fill it in.

Step 5: Run OAuth Setup Script

The setup_oauth.py script handles the OAuth 2.0 authorization flow and generates a refresh token with all required scopes.

Run the setup script

From the project root directory:

.venv/bin/python scripts/setup_oauth.py

The script will:

Read your GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET from .env
Start a local web server
Open your default browser

Authorize in browser

In the browser window that opens:

Select your Google account
Review the permissions being requested:
- View and edit your Google Calendar events
- Read your Gmail messages (if Gmail API enabled)
- View your Google Docs documents (if Docs API enabled)
- Manage Google Meet settings (if Meet API enabled)
Click Continue or Allow

Verify token generation

After authorization, the script will:

Display a success message
Automatically write GOOGLE_REFRESH_TOKEN to your .env file

You should see:

Token guardado en GOOGLE_REFRESH_TOKEN.

Asana: cuando tengas tu Personal Access Token, añade ASANA_ACCESS_TOKEN en .env.
Listo. Prueba: .venv/bin/python run_morning.py

The refresh token is long-lived and allows Morning Brain Starter to access your Google services without requiring manual authorization each time.

Regenerating the Token

If you need to regenerate the token (e.g., to add new API scopes):

.venv/bin/python scripts/setup_oauth.py --regenerate

This will force a new OAuth flow even if GOOGLE_REFRESH_TOKEN already exists.

Step 6: Configure Calendar Selection

By default, Morning Brain Starter reads only your primary Google Calendar. To monitor multiple calendars or specific named calendars:

Edit calendar.yaml

Open config/calendar.yaml and specify calendar names:

# Calendarios que revisa el morning. Nombres exactos como en Google Calendar.
# Si está vacío o no existe, se usa solo el calendario principal (primary).

calendars:
  - Work
  - Personal
  - "Demo #hechoConIA"

Calendar names must match exactly as they appear in Google Calendar, including capitalization and special characters.

Override via environment variable (optional)

To quickly test with a single calendar, set the CALENDAR_NAME environment variable in .env:

# Opcional: único calendario a usar por nombre (prioritario sobre config/calendar*.yaml).
CALENDAR_NAME=Demo #hechoConIA

This takes priority over calendar.yaml.

Environment Variables Reference

Required Variables

GOOGLE_CLIENT_ID

string

required

OAuth 2.0 Client ID from Google Cloud Console.Where to get it: Google Cloud Console → APIs & Services → Credentials → Create OAuth Client ID (Desktop app)Example: 123456789-abc123.apps.googleusercontent.com

GOOGLE_CLIENT_SECRET

string

required

OAuth 2.0 Client Secret from Google Cloud Console.Where to get it: Same location as Client ID, shown when creating credentials.Example: GOCSPX-abc123xyz789

GOOGLE_REFRESH_TOKEN

string

required

Long-lived refresh token generated by running setup_oauth.py.How to generate: Run .venv/bin/python scripts/setup_oauth.py and authorize in the browser.Note: This is automatically written to .env by the setup script.

Optional Variables

CALENDAR_NAME

string

Override to use a single specific calendar by name. Takes priority over config/calendar.yaml.Example: CALENDAR_NAME=Work

GOOGLE_CALENDAR_EMAIL

string

Your Google Calendar email address. Used for accepting/declining calendar invites when the API doesn’t return ‘self’ in the event.Example: [email protected]

OAuth Scopes Requested

The setup_oauth.py script requests these scopes in a single authorization flow:

GOOGLE_SCOPES = [
    # Calendar: read events and modify (add Meet, accept/decline, update description)
    "https://www.googleapis.com/auth/calendar.readonly",
    "https://www.googleapis.com/auth/calendar.events",
    # Meet: enable transcription in meeting spaces
    "https://www.googleapis.com/auth/meetings.space.settings",
    # Gmail: read recent email (morning briefing, bitácoras)
    "https://www.googleapis.com/auth/gmail.readonly",
    # Docs: read linked Docs content (transcriptions in calendar events)
    "https://www.googleapis.com/auth/documents.readonly",
]

Even if you don’t plan to use Gmail or Docs features, authorizing all scopes now means you won’t need to regenerate the token later.

Troubleshooting

Error: 'Falta GOOGLE_CLIENT_ID o GOOGLE_CLIENT_SECRET'

The setup script cannot find your credentials in .env.Solution:

Verify resources/secrets/.env exists
Check that GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set (not empty)
Ensure there are no typos in the variable names

Error: 'redirect_uri_mismatch'

The redirect URI in your OAuth consent screen doesn’t match what the script expects.Solution:

In Google Cloud Console → Credentials → Edit your OAuth Client ID
Under “Authorized redirect URIs”, ensure http://localhost is listed
The script uses a random port, so just http://localhost without a port should work

Browser doesn't open automatically

The script tries to open your default browser but may fail in some environments.Solution:

Look for a URL in the terminal output (starts with https://accounts.google.com/o/oauth2/auth...)
Manually copy and paste this URL into your browser
Complete the authorization flow

Token expired or invalid error when running morning

Your refresh token may have been revoked or expired.Solution:

Regenerate the token: .venv/bin/python scripts/setup_oauth.py --regenerate
Complete the authorization flow again

Need to add new API scopes

If you enabled a new API (like Docs or Meet) after generating your token.Solution:

Enable the API in Google Cloud Console
Regenerate the token: .venv/bin/python scripts/setup_oauth.py --regenerate
The new scopes will be included in the authorization request

Testing Your Configuration

After completing setup, test your configuration:

.venv/bin/python run_morning.py

You should see:

Your calendar events for today
Client meetings identified
Any relevant context from bitácoras

If you see calendar events, your Google Calendar integration is working correctly!

Next Steps

Client Configuration

Map calendar events to clients and configure bitácoras

Asana Integration

Optional: Add task management

Gmail Integration

Optional: Include recent emails

Usage Guide

Learn how to use Morning Brain Starter

Get Started

Configuration

Overview

Prerequisites

Step 1: Create Google Cloud Project

Step 2: Enable Google APIs

Step 3: Create OAuth 2.0 Credentials

Step 4: Configure Environment Variables

Step 5: Run OAuth Setup Script

Regenerating the Token

Step 6: Configure Calendar Selection

Environment Variables Reference

Required Variables

Optional Variables

OAuth Scopes Requested

Troubleshooting

Testing Your Configuration

Next Steps

Client Configuration

Asana Integration

Gmail Integration

Usage Guide

Build docs developers (and LLMs) love

Get Started

Configuration

​Overview

​Prerequisites

​Step 1: Create Google Cloud Project

​Step 2: Enable Google APIs

​Step 3: Create OAuth 2.0 Credentials

​Step 4: Configure Environment Variables

​Step 5: Run OAuth Setup Script

​Regenerating the Token

​Step 6: Configure Calendar Selection

​Environment Variables Reference

​Required Variables

​Optional Variables

​OAuth Scopes Requested

​Troubleshooting

​Testing Your Configuration

​Next Steps

Client Configuration

Asana Integration

Gmail Integration

Usage Guide

Build docs developers (and LLMs) love

Overview

Prerequisites

Step 1: Create Google Cloud Project

Step 2: Enable Google APIs

Step 3: Create OAuth 2.0 Credentials

Step 4: Configure Environment Variables

Step 5: Run OAuth Setup Script

Regenerating the Token

Step 6: Configure Calendar Selection

Environment Variables Reference

Required Variables

Optional Variables

OAuth Scopes Requested

Troubleshooting

Testing Your Configuration

Next Steps