Google Drive

Google Drive integration gives task-runner agents access to your Google Drive files (and other Google Workspace products like Gmail, Calendar, and Docs) during task execution. When connected, agents can list, read, create, update, and delete files and folders on your behalf.

The integration uses the gws CLI (Google Workspace CLI), which is bundled into the Errand task runner image. The CLI is invoked directly by the agent as a command — there is no MCP server in between. Errand’s own server handles the OAuth flow and stores the resulting refresh token in its encrypted credential store.

Use a dedicated account

We recommend connecting a dedicated Google account rather than your personal one. Errand agents will have full read/write access to all files in the connected Drive, including the ability to delete them. Using a separate account lets you share only the specific files and folders Errand needs, keeping the rest of your personal files out of reach.

Use Errand Cloud for Connecting

Setting up OAuth credentials for Google Drive requires a publicly accessible callback URL. If your Errand installation runs on a local network, Errand Cloud can handle the authentication flow for you — no public URL needed.

Prerequisites

• An OAuth 2.0 client must be registered in the Google Cloud Console
• The user connecting their account must have a Google account with Google Drive access
• The gws CLI is pre-installed in the task runner image — no additional deployment is required

Step 1: Create a Google Cloud project

1. Go to the Google Cloud Console
2. Click the project selector at the top and choose New Project
3. Give it a name (e.g. “Errand”) and click Create
4. Select the newly created project

Step 2: Configure the OAuth consent screen

1. Navigate to APIs & Services > OAuth consent screen
2. Choose the user type:
   • Internal — if all users are in your Google Workspace organization (no app review needed)
   • External — if users outside your organization need access (requires app review for production, or add test users)
3. Fill in the required fields:
   • App name: e.g. “Errand”
   • User support email: your email
   • Developer contact email: your email
4. On the Scopes step, click Add or remove scopes and add:
   • https://www.googleapis.com/auth/drive (full Drive access)
5. If using External user type in testing mode, add your Google account email under Test users
6. Click Save and Continue through the remaining steps

Step 3: Create OAuth credentials

1. Navigate to APIs & Services > Credentials
2. Click Create Credentials > OAuth client ID
3. Configure:
   • Application type: Web application
   • Name: e.g. “Errand Web Client”
   • Authorized redirect URIs: Add your Errand callback URL:

     https://<your-domain>/api/integrations/google_drive/callback

     For local development:

     http://localhost:8000/api/integrations/google_drive/callback

4. Click Create and note the Client ID and Client Secret

Step 4: Enable the Google Drive API

1. Navigate to APIs & Services > Enabled APIs & services
2. Click Enable APIs and Services
3. Search for “Google Drive API” and click Enable

Step 5: Configure Errand

Provide the OAuth credentials as environment variables to the Errand server.

Docker Compose

Add to your .env file:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

These are already wired into the errand service in docker-compose.yml.

Kubernetes (Helm)

Create a Kubernetes secret:

kubectl create secret generic errand-gdrive-oauth \
  --from-literal=GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com" \
  --from-literal=GOOGLE_CLIENT_SECRET="your-client-secret" \
  -n errand

Set the secret name in your Helm values (the gdrive: key is retained for backward compatibility but the credentials are now read by the Errand server directly — the standalone Google Drive MCP server was retired when the gws CLI took over):

gdrive:
  existingSecret: errand-gdrive-oauth

Step 6: Connect your account

1. Open the Errand UI and navigate to Settings > Integrations
2. The Google Drive card should show a Connect button (if it’s greyed out, check that the environment variables are set and the MCP server is running)
3. Click Connect — you’ll be redirected to Google’s consent screen
4. Sign in and grant access to your Google Drive
5. You’ll be redirected back to Errand — the card should now show your connected account

How it works

Once connected:

• The task manager loads your Google Drive credentials before each task execution
• If the OAuth access token has expired, the task manager automatically refreshes it using the stored refresh token
• The gws CLI is pre-installed in the task runner image at /usr/local/bin/gws; the task manager injects the access token so the CLI can authenticate without prompting
• The task runner’s AI agent invokes gws drive … (and gws gmail …, gws calendar …, etc.) directly. Reference skills are bundled at /opt/system-skills/gws/gws-*/SKILL.md — agents are expected to read the relevant skill before issuing commands
• Cloud storage instructions are appended to the system prompt to guide the agent

Task profile control

The gws skill set participates in task profile filtering in the same way that MCP servers do. If a profile specifies a skills filter, the gws set must be included for agents using that profile to access Google Workspace. If the profile’s skills filter is empty, all available skills (including gws) are available by default.

Disconnecting

To disconnect your Google Drive account:

1. Go to Settings > Integrations
2. Click Disconnect on the Google Drive card
3. The stored credentials are deleted from Errand

You can also revoke access from Google’s side at myaccount.google.com/permissions.

Troubleshooting

Issue	Solution
Card is greyed out	Check that GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are both set in the server’s environment
”Provider not configured” error on Connect	The OAuth client credentials are not set in the server’s environment
Consent screen shows “unverified app” warning	Normal for External apps in testing mode — click “Advanced” then “Go to (app name)“
Token refresh fails after some time	The user may have revoked access — disconnect and reconnect
Agent reports auth errors during task	The access token may have expired mid-task (tasks longer than 1 hour) — this is a known limitation