google-workspace

name	google-workspace
description	Google Workspace API operations for Apps Script, Docs, Slides, Sheets, Gmail, Calendar, Drive-backed files, and Google Keep. Use when the user asks to search/read/send Gmail, manage Calendar events, read/write Sheets ranges, create/update Docs or Slides, run Apps Script functions, inspect Drive files, or access Keep notes through Google APIs.
metadata	{"all_agents":{"emoji":"G","requires":{"bins":["python3"]}},"secrets":[{"name":"GOOGLE_ACCESS_TOKEN","description":"OAuth2 user access token with the requested Google Workspace scopes","required":false},{"name":"GOOGLE_APPLICATION_CREDENTIALS","description":"Path to a service-account JSON file for server-to-server flows","required":false}]}

Google Workspace

Use Google Workspace REST APIs for Gmail, Calendar, Sheets, Docs, Slides, Apps Script, Drive file discovery, and Keep notes.

First Choice

Use scripts/google-api.py for direct REST calls. It reads an access token from GOOGLE_ACCESS_TOKEN; if that is missing, it tries gcloud auth print-access-token, then gcloud auth application-default print-access-token.

python3 skills/google-workspace/scripts/google-api.py GET /gmail/v1/users/me/messages --query maxResults=10
python3 skills/google-workspace/scripts/google-api.py GET /calendar/v3/users/me/calendarList
python3 skills/google-workspace/scripts/google-api.py GET /drive/v3/files --query "q=mimeType='application/vnd.google-apps.spreadsheet'" --query fields="files(id,name,mimeType,modifiedTime)"

Never pass access tokens on the command line. Put them in the secret store or let gcloud provide them.

Authentication

For a personal account or normal delegated Workspace user access, use OAuth user credentials:

gcloud auth application-default login \
  --client-id-file=~/.all-agents/auth/google-oauth-client.json \
  --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/gmail.send,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/documents,https://www.googleapis.com/auth/presentations,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/script.projects,https://www.googleapis.com/auth/script.scriptapp

gcloud auth application-default print-access-token

Google blocks the default Cloud SDK OAuth client for many sensitive Workspace scopes. Create a Google Auth Platform OAuth client with application type "Desktop app", download the JSON outside the repo, store it at ~/.all-agents/auth/google-oauth-client.json, and pass it with --client-id-file. Do not paste the client secret into chat or logs.

If gcloud auth print-access-token is not using the needed account/scopes, ask the user to re-authenticate outside the agent session. Do not paste OAuth client secrets or refresh tokens into chat.

For Workspace domain automation, use a service account with domain-wide delegation only after an admin has approved the exact scopes. Keep service-account JSON outside the repo and reference it with GOOGLE_APPLICATION_CREDENTIALS.

See references/auth.md for scope selection and setup notes.

Common APIs

Base URL shortcuts used by google-api.py:

Product	Base path	Common scopes
Gmail	/gmail/v1/users/me/...	gmail.readonly, gmail.modify, gmail.send
Calendar	/calendar/v3/...	calendar, calendar.events
Drive	/drive/v3/...	drive, drive.file, drive.metadata.readonly
Sheets	/v4/spreadsheets/...	spreadsheets
Docs	/v1/documents/...	documents
Slides	/v1/presentations/...	presentations
Apps Script	/v1/projects/..., /v1/scripts/{scriptId}:run	script.projects, script.scriptapp
Keep	/v1/notes...	keep

The helper maps paths to the right host automatically. Full URLs are also accepted.

Gmail

List recent messages:

python3 skills/google-workspace/scripts/google-api.py GET /gmail/v1/users/me/messages \
  --query maxResults=10 \
  --query q="newer_than:7d"

Read a message:

python3 skills/google-workspace/scripts/google-api.py GET /gmail/v1/users/me/messages/MESSAGE_ID \
  --query format=full

Send email requires RFC 2822 content base64url-encoded as raw:

python3 - <<'PY'
import base64, email.message, json
msg = email.message.EmailMessage()
msg['To'] = '[e-mail]'
msg['From'] = '[e-mail]'
msg['Subject'] = 'Hello'
msg.set_content('Body text')
raw = base64.urlsafe_b64encode(msg.as_bytes()).decode().rstrip('=')
print(json.dumps({'raw': raw}))
PY
# Save that JSON, then:
python3 skills/google-workspace/scripts/google-api.py POST /gmail/v1/users/me/messages/send --data @send.json

Calendar

List upcoming events:

python3 skills/google-workspace/scripts/google-api.py GET /calendar/v3/calendars/primary/events \
  --query singleEvents=true \
  --query orderBy=startTime \
  --query maxResults=10

Create an event:

python3 skills/google-workspace/scripts/google-api.py POST /calendar/v3/calendars/primary/events --data '{
  "summary": "Planning",
  "start": {"dateTime": "2026-05-18T09:00:00+08:00"},
  "end": {"dateTime": "2026-05-18T09:30:00+08:00"}
}'

Sheets

Read a range:

python3 skills/google-workspace/scripts/google-api.py GET \
  "/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D20"

Write a range:

python3 skills/google-workspace/scripts/google-api.py PUT \
  "/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:B2" \
  --query valueInputOption=USER_ENTERED \
  --data '{"values":[["Name","Score"],["Alice",95]]}'

Use :batchUpdate for formatting, adding sheets, filters, protected ranges, charts, and structural changes.

Docs

Get document structure:

python3 skills/google-workspace/scripts/google-api.py GET /v1/documents/DOCUMENT_ID

Insert text:

python3 skills/google-workspace/scripts/google-api.py POST /v1/documents/DOCUMENT_ID:batchUpdate --data '{
  "requests": [{"insertText": {"location": {"index": 1}, "text": "Hello\n"}}]
}'

Use Docs batchUpdate request arrays for edits. Inspect current indexes before mutating.

Slides

Get a presentation:

python3 skills/google-workspace/scripts/google-api.py GET /v1/presentations/PRESENTATION_ID

Add a slide:

python3 skills/google-workspace/scripts/google-api.py POST /v1/presentations/PRESENTATION_ID:batchUpdate --data '{
  "requests": [{"createSlide": {"slideLayoutReference": {"predefinedLayout": "TITLE_AND_BODY"}}}]
}'

Use Slides batchUpdate for text boxes, images, shapes, speaker notes, layouts, and styling.

Apps Script

List script projects requires Drive search for Apps Script MIME type:

python3 skills/google-workspace/scripts/google-api.py GET /drive/v3/files \
  --query "q=mimeType='application/vnd.google-apps.script'" \
  --query fields="files(id,name,modifiedTime)"

Run a deployed Apps Script function:

python3 skills/google-workspace/scripts/google-api.py POST /v1/scripts/SCRIPT_ID:run --data '{
  "function": "main",
  "parameters": [],
  "devMode": false
}'

The Apps Script project must be configured to allow execution by the authenticated user. API calls made inside the script can require additional OAuth scopes declared in appsscript.json.

Keep

Google Keep API is available for supported Google Workspace accounts and usually needs admin/API access. It may not work for all consumer accounts, and Google may reject the https://www.googleapis.com/auth/keep scope unless the OAuth app is approved for it.

List notes:

python3 skills/google-workspace/scripts/google-api.py GET /v1/notes --query pageSize=20

Create a text note:

python3 skills/google-workspace/scripts/google-api.py POST /v1/notes --data '{
  "title": "Quick note",
  "body": {"text": {"text": "Remember this"}}
}'

Guardrails

• Ask before sending email, modifying Calendar events, deleting files, or changing Docs/Slides/Sheets content.
• Prefer read-only scopes until a write action is needed.
• Do not print access tokens, refresh tokens, client secrets, service-account JSON, or raw email content unless the user explicitly asks for a narrow excerpt.
• Use Drive fields= filters and Gmail query filters to reduce returned data.
• For destructive actions, show the target resource ID/name and wait for confirmation.

References

• references/auth.md - OAuth, service-account, and scope notes.
• references/api-cheatsheet.md - endpoint map for Apps Script, Docs, Slides, Sheets, Gmail, Calendar, Keep, and Drive.