Google

# Open the Cloud Console API Library for your project
# Replace PROJECT_ID with your actual project ID
open "https://console.cloud.google.com/apis/library?project=PROJECT_ID"

# APIs to enable (click "Enable" on each):
#   Gmail API         → https://console.cloud.google.com/apis/library/gmail.googleapis.com
#   Google Calendar   → https://console.cloud.google.com/apis/library/calendar-json.googleapis.com
#   Google Drive      → https://console.cloud.google.com/apis/library/drive.googleapis.com
#   Google Sheets     → https://console.cloud.google.com/apis/library/sheets.googleapis.com
#   Google Docs       → https://console.cloud.google.com/apis/library/docs.googleapis.com
#   Cloud Resource    → https://console.cloud.google.com/apis/library/cloudresourcemanager.googleapis.com

# Or use the gcloud CLI to enable them all at once:
gcloud config set project PROJECT_ID
gcloud services enable gmail.googleapis.com
gcloud services enable calendar-json.googleapis.com
gcloud services enable drive.googleapis.com
gcloud services enable sheets.googleapis.com
gcloud services enable docs.googleapis.com

# OAuth consent screen checklist
#
# 1. Go to: APIs & Services → OAuth consent screen
# 2. Choose user type:
#    - Internal  → only accounts in your Google Workspace org can use it
#                  (no verification required, no 100-user test cap)
#    - External  → any Google account can use it
#                  (requires verification if published; limit 100 test users while in testing)
#
# 3. Fill in required fields:
#    - App name:         "Conductor MCP"        (shown on consent screen)
#    - User support email:  your email
#    - Developer contact:   your email
#
# 4. Add scopes (click "Add or Remove Scopes"):
#    Paste each scope URI and click "Update":
#
#    https://www.googleapis.com/auth/gmail.send
#    https://www.googleapis.com/auth/gmail.readonly
#    https://www.googleapis.com/auth/gmail.modify
#    https://www.googleapis.com/auth/gmail.labels
#    https://www.googleapis.com/auth/calendar
#    https://www.googleapis.com/auth/calendar.events
#    https://www.googleapis.com/auth/drive
#    https://www.googleapis.com/auth/drive.file
#    https://www.googleapis.com/auth/drive.readonly
#    https://www.googleapis.com/auth/spreadsheets
#    https://www.googleapis.com/auth/spreadsheets.readonly
#
# 5. Test users (External only):
#    Add every Google account that will use Conductor here.
#    Users NOT on this list will see "Access blocked" until the app is published.
#
# 6. Save and continue.

# Creating OAuth 2.0 credentials
#
# 1. Go to: APIs & Services → Credentials
# 2. Click "+ Create Credentials" → "OAuth client ID"
# 3. Application type: Desktop app
#    ↑ IMPORTANT: Must be "Desktop app", not "Web application"
#      Web application requires a redirect URI server; Desktop app uses
#      the loopback address (127.0.0.1) which Conductor handles automatically.
# 4. Name: "Conductor MCP Desktop"
# 5. Click Create
# 6. Click "Download JSON" on the resulting dialog
#    (or download it later from the Credentials list → pencil icon → Download JSON)
#
# The downloaded file looks like this:
# {
#   "installed": {
#     "client_id": "123456789-abc.apps.googleusercontent.com",
#     "project_id": "my-project",
#     "auth_uri": "https://accounts.google.com/o/oauth2/auth",
#     "token_uri": "https://oauth2.googleapis.com/token",
#     "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
#     "client_secret": "GOCSPX-...",
#     "redirect_uris": ["http://localhost"]
#   }
# }
#
# Save it at: ~/.conductor/google-credentials.json
# (Or any path — you'll reference it in your config)
mkdir -p ~/.conductor
mv ~/Downloads/client_secret_*.json ~/.conductor/google-credentials.json
chmod 600 ~/.conductor/google-credentials.json

# Running the first-time OAuth flow
#
# After configuring credentials in ~/.conductor/config.json, run:
conductor auth google

# Conductor will:
# 1. Open your browser to Google's OAuth consent screen
# 2. You log in and grant the requested scopes
# 3. Google redirects to http://127.0.0.1:<random-port>/?code=...
# 4. Conductor captures the code and exchanges it for access + refresh tokens
# 5. Tokens are saved to ~/.conductor/tokens/google.json
#
# You should see:
# ✓ Google authorization complete
# ✓ Token saved to ~/.conductor/tokens/google.json
# ✓ Refresh token stored — you won't need to re-authorize
#
# If a browser doesn't open, Conductor prints the URL:
# Open this URL in your browser:
# https://accounts.google.com/o/oauth2/auth?client_id=...&scope=...
#
# After authorizing, paste the resulting code:
# conductor auth google --code 4/0AX...

# Token file location
cat ~/.conductor/tokens/google.json

# Structure:
# {
#   "access_token": "ya29.a0A...",      ← short-lived (1 hour)
#   "refresh_token": "1//0g...",        ← long-lived, used to get new access tokens
#   "scope": "https://www.googleapis.com/auth/gmail.send ...",
#   "token_type": "Bearer",
#   "expiry_date": 1712345678901        ← milliseconds epoch
# }
#
# Conductor checks expiry_date before every API call.
# If within 5 minutes of expiry (or already expired), it automatically
# calls the token endpoint with the refresh_token to get a new access_token.
# The refresh_token itself does not expire unless:
#   - The user revokes access
#   - The OAuth app is in "Testing" mode and the refresh token is >7 days old
#   - The user changes their Google account password (in some configurations)
#   - The app exceeds 50 refresh tokens per user (oldest are invalidated)

# Revoke access (from Google's side):
open "https://myaccount.google.com/permissions"
# Find "Conductor MCP" and click "Remove Access"

# Re-authorize after revocation:
rm ~/.conductor/tokens/google.json
conductor auth google

# ~/.conductor/config.json — Gmail plugin
{
  "plugins": {
    "gmail": {
      "credentialsFile": "~/.conductor/google-credentials.json",
      "tokenFile": "~/.conductor/tokens/google.json",
      "scopes": [
        "https://www.googleapis.com/auth/gmail.send",
        "https://www.googleapis.com/auth/gmail.readonly",
        "https://www.googleapis.com/auth/gmail.modify",
        "https://www.googleapis.com/auth/gmail.labels"
      ],
      "defaultFrom": "me",
      "maxResults": 50,
      "historyDays": 30
    }
  }
}

# Available Gmail tools and example usage

# gmail.read — fetch a specific message by ID
# Returns: subject, from, to, date, body (plain text + HTML), headers, attachments list
# Example prompt: "Read email with ID 18c3f..."

# gmail.search — search messages with Gmail query syntax
# Supports full Gmail search operators: from:, to:, subject:, has:attachment,
#   is:unread, is:starred, after:2024/01/01, before:2024/12/31, label:inbox, etc.
# Example prompts:
#   "Find all emails from boss@company.com this week"
#   "Search for unread emails with attachments in my inbox"
#   "Find emails with subject containing 'invoice' from the last 30 days"

# gmail.send — compose and send an email
# Supports: to, cc, bcc, subject, body (plain or HTML), replyTo, attachments
# Example prompts:
#   "Send an email to alice@example.com about the project update"
#   "Reply to the latest email from Bob"
#   "Send a meeting invite email to the team"

# gmail.label — add/remove labels on messages or threads
# Supports: addLabelIds, removeLabelIds, using label names or IDs
# Example prompts:
#   "Label this email as 'important'"
#   "Remove the 'todo' label from this thread"
#   "Mark message 18c3f as read"

# gmail.archive — move messages out of inbox (add ARCHIVED, remove INBOX)
# Example prompts:
#   "Archive all read emails older than 7 days"
#   "Archive this thread"

# gmail.delete — permanently delete messages (move to Trash or delete from Trash)
# Example prompts:
#   "Delete the email with ID 18c3f"
#   "Empty trash"

# gmail.threads — list, read, or modify entire threads
# Returns all messages in a thread with full metadata
# Example prompts:
#   "Show me the full thread for this conversation"
#   "How many emails are in this thread?"

# ~/.conductor/config.json — Google Calendar plugin
{
  "plugins": {
    "gcal": {
      "credentialsFile": "~/.conductor/google-credentials.json",
      "tokenFile": "~/.conductor/tokens/google.json",
      "scopes": [
        "https://www.googleapis.com/auth/calendar",
        "https://www.googleapis.com/auth/calendar.events"
      ],
      "defaultCalendarId": "primary",
      "timezone": "America/New_York",
      "maxResults": 100,
      "lookAheadDays": 30
    }
  }
}

# Finding your Calendar ID
#
# Primary calendar: use the string "primary" — it always resolves to
#   the authenticated user's main calendar.
#
# Other calendars (shared, project, team):
# 1. Open Google Calendar at calendar.google.com
# 2. In the left sidebar, hover over the calendar name
# 3. Click the three-dot menu → "Settings and sharing"
# 4. Scroll down to "Integrate calendar"
# 5. Copy the "Calendar ID" — looks like one of:
#      primary calendar: you@gmail.com
#      other calendar:   abc123xyz@group.calendar.google.com
#      Google-managed:   en.usa#holiday@group.v.calendar.google.com
#
# For service accounts: the calendar must be shared with the service
# account email (e.g. conductor-mcp@project.iam.gserviceaccount.com)
# with at least "Make changes to events" permission.

# Multiple calendar config example:
{
  "plugins": {
    "gcal": {
      "credentialsFile": "~/.conductor/google-credentials.json",
      "calendars": [
        { "id": "primary", "name": "Personal" },
        { "id": "team@group.calendar.google.com", "name": "Team" },
        { "id": "en.usa#holiday@group.v.calendar.google.com", "name": "US Holidays" }
      ]
    }
  }
}

# Available Google Calendar tools

# gcal.list — list events in a date range
# Parameters: calendarId, timeMin, timeMax, maxResults, singleEvents, orderBy
# Example prompts:
#   "What's on my calendar this week?"
#   "List all events in the Team calendar for next month"
#   "Show me my schedule for tomorrow"

# gcal.create — create a new event
# Parameters: calendarId, summary, description, start, end, attendees,
#             location, recurrence, reminders, conferenceData (Meet link)
# Example prompts:
#   "Create a meeting called 'Sprint Review' on Friday at 2pm for 1 hour"
#   "Add a recurring standup every weekday at 9am"
#   "Schedule a call with alice@example.com for next Tuesday at 3pm, add a Meet link"

# gcal.update — update an existing event
# Parameters: calendarId, eventId, and any fields to change
# Example prompts:
#   "Move tomorrow's standup to 10am"
#   "Add bob@example.com to the Sprint Review meeting"
#   "Change the Sprint Review location to 'Conference Room B'"

# gcal.delete — delete an event
# Parameters: calendarId, eventId
# Example prompts:
#   "Cancel the 3pm meeting on Friday"
#   "Delete all events with 'draft' in the title"

# gcal.freebusy — query free/busy times for calendars or users
# Returns busy blocks; useful for finding meeting slots
# Example prompts:
#   "When is alice@example.com free tomorrow between 9am and 5pm?"
#   "Find a 1-hour slot for 3 people next week"
#   "Am I free on Thursday afternoon?"

# ~/.conductor/config.json — Google Drive plugin
{
  "plugins": {
    "drive": {
      "credentialsFile": "~/.conductor/google-credentials.json",
      "tokenFile": "~/.conductor/tokens/google.json",
      "scopes": [
        "https://www.googleapis.com/auth/drive"
      ],
      "pageSize": 100,
      "includeItemsFromAllDrives": true,
      "supportsAllDrives": true,
      "corpora": "allDrives"
    }
  }
}

# For read-only access (safer for CI or restricted use):
{
  "plugins": {
    "drive": {
      "credentialsFile": "~/.conductor/google-credentials.json",
      "scopes": [
        "https://www.googleapis.com/auth/drive.readonly"
      ]
    }
  }
}

# For creating/modifying only files that Conductor created (narrowest scope):
{
  "plugins": {
    "drive": {
      "credentialsFile": "~/.conductor/google-credentials.json",
      "scopes": [
        "https://www.googleapis.com/auth/drive.file"
      ]
    }
  }
}

# Finding a file's ID in Google Drive
#
# Method 1 — From the URL:
# When you open a file in Google Drive, the URL looks like:
#   https://drive.google.com/file/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms/view
#                                   ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑
#   File ID: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
#
# For Sheets/Docs/Slides the URL pattern is:
#   https://docs.google.com/spreadsheets/d/FILE_ID/edit
#   https://docs.google.com/document/d/FILE_ID/edit
#   https://docs.google.com/presentation/d/FILE_ID/edit
#
# Method 2 — Right-click → "Get link" → extract from the copied URL
#
# Method 3 — Use drive.list and search by name:
# "Find the file ID for the document named 'Q4 Report'"
#
# Shared Drives (Team Drives):
# The Drive ID is in the URL when you're inside a Shared Drive:
#   https://drive.google.com/drive/folders/DRIVE_ID
# Use this as the driveId parameter for Shared Drive operations.

# Working with Shared Drives (formerly Team Drives)
#
# Shared Drives have different permission semantics than My Drive:
#   - Files belong to the drive, not a user
#   - Membership levels: Viewer, Commenter, Contributor, Content Manager, Manager
#   - Service accounts must be added as a member of the Shared Drive
#
# Granting service account access to a Shared Drive:
# 1. Open the Shared Drive in drive.google.com
# 2. Click the down-arrow next to the drive name → "Manage members"
# 3. Add your service account email: conductor-mcp@project.iam.gserviceaccount.com
# 4. Set appropriate role (Contributor for read+write, Content Manager for full access)
#
# Config for Shared Drive operations:
{
  "plugins": {
    "drive": {
      "credentialsFile": "~/.conductor/google-credentials.json",
      "supportsAllDrives": true,
      "includeItemsFromAllDrives": true,
      "driveId": "0APN1..."
    }
  }
}

# Available Google Drive tools

# drive.list — list files and folders
# Supports: query (Drive query syntax), pageSize, driveId, corpora, orderBy
# Drive query examples:
#   name contains 'report'
#   mimeType = 'application/vnd.google-apps.spreadsheet'
#   modifiedTime > '2024-01-01T00:00:00'
#   'FOLDER_ID' in parents
#   trashed = false
# Example prompts:
#   "List all spreadsheets in my Drive"
#   "Show files in the 'Projects' folder"
#   "Find files modified in the last week"

# drive.read — read the content of a file
# Returns file content; auto-exports Google Docs/Sheets/Slides to text/csv/pdf
# Example prompts:
#   "Read the contents of the Q4 Report doc"
#   "Show me what's in file 1BxiMVs0..."
#   "Export the presentation as PDF"

# drive.upload — upload a new file or create a Google Doc/Sheet
# Supports: name, content, mimeType, parents (folder IDs), convert to Google format
# Example prompts:
#   "Upload this CSV as a new Google Sheet"
#   "Create a new Google Doc called 'Meeting Notes' in the Projects folder"
#   "Upload report.pdf to the Shared Drive"

# drive.share — share a file with users or make it public
# Supports: role (reader/writer/commenter/owner), type (user/group/domain/anyone)
# Example prompts:
#   "Share the Q4 Report with bob@example.com as editor"
#   "Make this file viewable by anyone with the link"
#   "Give the entire company domain read access to this folder"

# drive.delete — move to trash or permanently delete
# Example prompts:
#   "Delete the file named 'old-draft.docx'"
#   "Permanently delete everything in the trash"

# ~/.conductor/config.json — Google Sheets plugin
{
  "plugins": {
    "sheets": {
      "credentialsFile": "~/.conductor/google-credentials.json",
      "tokenFile": "~/.conductor/tokens/google.json",
      "scopes": [
        "https://www.googleapis.com/auth/spreadsheets"
      ],
      "valueInputOption": "USER_ENTERED",
      "valueRenderOption": "FORMATTED_VALUE",
      "dateTimeRenderOption": "FORMATTED_STRING"
    }
  }
}

# Finding the Spreadsheet ID
#
# Open the Google Sheet — the URL looks like:
#   https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms/edit#gid=0
#                                          ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑
# Spreadsheet ID: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
# Sheet (tab) name: visible in the tab bar at the bottom (default: "Sheet1")
#
# A1 notation reference:
#   A1             → single cell, column A row 1
#   A1:D10         → range from A1 to D10
#   Sheet1!A1:D10  → range on a specific sheet tab
#   A:A            → entire column A
#   1:1            → entire row 1
#   Sheet2!B2:B    → column B from row 2 onwards on Sheet2
#
# Named ranges:
#   If you've defined named ranges in the sheet (Data → Named ranges),
#   you can use the name directly: "SalesData", "Q4Totals", etc.
#
# valueInputOption:
#   USER_ENTERED → Google parses the value as if typed by a user
#                  "=SUM(A1:A10)" becomes a formula; "Jan 1" becomes a date
#   RAW          → stored exactly as provided, no interpretation
#                  "=SUM(A1:A10)" is stored as the literal string

# Available Google Sheets tools

# sheets.read — read values from a range
# Parameters: spreadsheetId, range (A1 notation or named range),
#             valueRenderOption, dateTimeRenderOption
# Example prompts:
#   "Read the data in Sheet1!A1:F100"
#   "Get all values in the 'SalesData' named range"
#   "Show me the headers in row 1"
#   "Read the entire first sheet"

# sheets.write — write values to a range (overwrites existing)
# Parameters: spreadsheetId, range, values (2D array), valueInputOption
# Example prompts:
#   "Write these numbers to cells B2:B10"
#   "Update cell C5 to 'Complete'"
#   "Write a formula =SUM(B2:B10) to cell B11"

# sheets.append — append rows after the last row with data
# Does not overwrite existing data; finds the first empty row at end of table
# Parameters: spreadsheetId, range (defines the table), values, valueInputOption
# Example prompts:
#   "Append a new row with today's date and the sales total"
#   "Add these 5 records to the end of the table"

# sheets.clear — clear values in a range (keeps formatting)
# Parameters: spreadsheetId, range
# Example prompts:
#   "Clear the data in B2:F50 but keep the headers"
#   "Wipe the entire Sheet2"

# Creating a service account
#
# 1. Go to: IAM & Admin → Service Accounts
# 2. Click "+ Create Service Account"
# 3. Name: "conductor-mcp"
# 4. Description: "Conductor MCP server service account"
# 5. Click "Create and Continue"
# 6. Grant roles (optional at creation, add later if needed):
#    - For Drive:   "Storage Object Viewer" or custom role
#    - For Sheets:  "Viewer" or "Editor"
#    - For GCP APIs: appropriate roles per service
# 7. Click "Done"
#
# Download the key:
# 1. Click on the service account you just created
# 2. Go to "Keys" tab
# 3. Click "Add Key" → "Create new key"
# 4. Key type: JSON → Create
# 5. The JSON key file downloads automatically
#
# Save it securely:
mkdir -p ~/.conductor
mv ~/Downloads/my-project-*.json ~/.conductor/google-service-account.json
chmod 600 ~/.conductor/google-service-account.json
#
# The key file looks like:
# {
#   "type": "service_account",
#   "project_id": "my-project",
#   "private_key_id": "abc123",
#   "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...",
#   "client_email": "conductor-mcp@my-project.iam.gserviceaccount.com",
#   "client_id": "...",
#   "token_uri": "https://oauth2.googleapis.com/token"
# }

# Sharing Drive files/folders with a service account
#
# Service accounts are like their own Google users — they have an email:
#   conductor-mcp@my-project.iam.gserviceaccount.com
#
# They do NOT have their own "My Drive". You must explicitly share files
# or folders with the service account email, just like sharing with a person.
#
# To share a specific file:
# 1. Right-click the file in Google Drive
# 2. "Share" → enter the service account email
# 3. Set role: Viewer (read-only) or Editor (read + write)
# 4. Uncheck "Notify people" (the email bounces — no inbox)
# 5. Click "Share"
#
# To share an entire folder (all files inside inherit access):
# Same as above but done on the folder.
#
# For Shared Drives: add service account as member (Manager, Content Manager, or Contributor)
# For Sheets: share the specific spreadsheet with the service account email
# For Calendar: share the calendar with the service account email via calendar settings

# Verify access with gcloud:
gcloud auth activate-service-account --key-file=~/.conductor/google-service-account.json
gcloud auth list

# Granting domain-wide delegation (Google Workspace only)
#
# This lets the service account impersonate any user in your org.
# Required for: reading/sending email AS a user, accessing their calendar, etc.
#
# Step 1 — Enable delegation on the service account:
# IAM & Admin → Service Accounts → your account → "Edit" (pencil) →
# "Show advanced settings" → tick "Enable G Suite Domain-wide Delegation" → Save
#
# Step 2 — Note the OAuth2 client ID shown under "Domain-wide delegation"
# It looks like: 123456789012345678901
#
# Step 3 — Authorize in Google Workspace Admin Console:
# admin.google.com → Security → Access and data control →
# API controls → Manage Domain Wide Delegation → Add new
#
# Client ID: <the numeric ID from step 2>
# OAuth Scopes (comma-separated):
https://www.googleapis.com/auth/gmail.send,https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/spreadsheets
#
# Step 4 — In your Conductor config, set the subject (user to impersonate):
# "google": {
#   "serviceAccountFile": "~/.conductor/google-service-account.json",
#   "subject": "user@yourdomain.com"
# }

# ~/.conductor/config.json — using service account instead of OAuth
{
  "plugins": {
    "gmail": {
      "serviceAccountFile": "~/.conductor/google-service-account.json",
      "subject": "user@yourdomain.com",
      "scopes": [
        "https://www.googleapis.com/auth/gmail.send",
        "https://www.googleapis.com/auth/gmail.readonly"
      ]
    },
    "gcal": {
      "serviceAccountFile": "~/.conductor/google-service-account.json",
      "subject": "user@yourdomain.com",
      "defaultCalendarId": "user@yourdomain.com",
      "scopes": [
        "https://www.googleapis.com/auth/calendar"
      ]
    },
    "drive": {
      "serviceAccountFile": "~/.conductor/google-service-account.json",
      "scopes": [
        "https://www.googleapis.com/auth/drive"
      ],
      "supportsAllDrives": true
    },
    "sheets": {
      "serviceAccountFile": "~/.conductor/google-service-account.json",
      "scopes": [
        "https://www.googleapis.com/auth/spreadsheets"
      ]
    }
  }
}