Google Workspace
Agenties can connect to Gmail, Google Calendar, and Google Drive using your own Google Cloud OAuth credentials. Once connected, agents can read and send email, list or create calendar events, and read or upload Drive files through the MCP tool surface.
npm run dev) because the OAuth bridge and keychain storage run in the Tauri sidecar.Prerequisites
Agenties does not bundle any Google OAuth credentials. You must create your own OAuth 2.0 client in Google Cloud Console and supply the Client ID and Client Secret to Agenties. This is a one-time setup per machine.
1. Create a Google Cloud project
Go to console.cloud.google.com and create a new project (or reuse an existing one). The project is only a container — it does not need billing enabled for the OAuth flow itself.
2. Enable the required APIs
In your project, navigate to APIs & Services → Library and enable all three:
| API | Used for |
|---|---|
| Gmail API | gmail_read, gmail_send |
| Google Calendar API | calendar_list, calendar_create |
| Google Drive API | drive_read, drive_upload |
3. Create an OAuth 2.0 client ID
Go to APIs & Services → Credentials → Create credentials → OAuth client ID. Choose Desktop app as the application type. Then add the following as an authorised redirect URI:
After saving, download or copy the Client ID and Client Secret — you will enter these in Agenties.
Setup in Agenties
Open the desktop app and go to Settings → Integrations → Google Workspace.
| Step | What to do |
|---|---|
| 1. Configure credentials | Enter the Client ID and Client Secret from Google Cloud Console, then click Save credentials. These are stored in the OS keychain — they never leave your machine. |
| 2. Connect Google account | Click Connect Google Workspace. Agenties opens your browser to the Google OAuth consent screen. Sign in with the account you want to connect and grant the requested permissions. |
| 3. Verify | After authorising, the browser tab shows "Connected!" and Agenties shows the connected email address and active scopes. The OAuth flow has a 2-minute timeout. |
Permissions requested
During the OAuth consent screen Google will ask for the following permissions. All are requested upfront so agents can use any tool without a second consent flow.
| Scope | Permission |
|---|---|
| openid, email, profile | Read your basic account info and email address (used to display the connected account) |
| gmail.readonly | Read (but not modify or delete) your Gmail messages |
| gmail.send | Send email from your Gmail account |
| calendar | View and create events on your Google Calendar |
| drive | View and upload files in your Google Drive |
Token storage
All credentials are stored in the OS keychain via the keytar library — no tokens are written to disk or sent to any Agenties server.
| What is stored | Keychain service | Platform |
|---|---|---|
| OAuth config (Client ID + Client Secret) | agenties-google-oauth | Windows Credential Manager / macOS Keychain / Linux Secret Service |
| Tokens (access + refresh + email + scopes) | agenties-google-workspace | Windows Credential Manager / macOS Keychain / Linux Secret Service |
Access tokens are refreshed automatically using the stored refresh token. No re-authorisation is needed unless you revoke access in your Google Account settings.
Check connection status
Call google_workspace_status before any Google tool to confirm the connection is active and see which scopes are available. It reads from the OS keychain and never exposes raw tokens.
| Tool | Parameters | Returns |
|---|---|---|
google_workspace_status | — | credentialsConfigured, connected, email, scopes[], expiresAt |
Gmail
| Tool | Parameters | Notes |
|---|---|---|
gmail_read | query? (string), maxResults? (1–20, default 10) | Returns message IDs and snippets — not full bodies. Use Gmail search syntax: from:, subject:, is:unread, newer_than:7d. |
gmail_send | to (required), subject (required), body (required) | Sends a plain-text email from the connected account. HTML is not supported. |
gmail_send sends real email immediately from your connected account. Use the Agenties permission model to gate sensitive or client-facing sends.Google Calendar
| Tool | Parameters | Notes |
|---|---|---|
calendar_list | calendarId? (default: primary), timeMin? (RFC3339, default: now), maxResults? (1–50, default 10) | Lists upcoming events ordered by start time. |
calendar_create | summary (required), start (required), end (required), description?, calendarId? (default: primary) | start and end must be RFC3339 dateTime strings, e.g. 2026-06-15T10:00:00+02:00. |
Google Drive
| Tool | Parameters | Notes |
|---|---|---|
drive_read | fileId? (string), query? (string), pageSize? (1–50, default 10) | Without fileId: lists files with optional query. With fileId: downloads the file content using alt=media. |
drive_upload | name (required), content (required), mimeType? (default: text/plain) | Uploads a small plain-text file. Always creates a new file — it does not update an existing one. |
drive_read with a fileId uses alt=media, which works for plain files (PDF, text, images) but not for Google Docs, Sheets, or Slides — those are Google-native formats that require export. drive_upload only supports plain-text content; binary uploads are not supported.Common use cases
| Use case | Tools involved |
|---|---|
| Morning briefing | gmail_read + calendar_list → render_artifact for a Markdown digest |
| Meeting scheduler | calendar_list to find a free slot, then calendar_create |
| Send report after deploy | gmail_send triggered after a successful build or Vercel deployment |
| Pull a spec into agent context | drive_read to fetch a plain-text or PDF brief before coding |
| Archive agent output | drive_upload to save a generated report or summary |
Known limitations
| Limitation | Detail |
|---|---|
| No full email body in gmail_read | The tool returns message IDs and snippets only. Full body retrieval by message ID is not implemented. |
| drive_read cannot export Google-native files | Google Docs, Sheets, and Slides require an export format — direct download via alt=media returns an error. |
| drive_upload creates a new file every time | There is no update/overwrite path. A new Drive file is created on every call. |
| Plain text only for drive_upload | Binary or rich-format content is not supported. |
| OAuth timeout is 2 minutes | If the browser flow is not completed within 2 minutes, the connection attempt fails and you must try again. |
| Desktop app only | The integration requires the Tauri desktop app. Browser dev mode has no sidecar and no keychain access. |