google-skillv1.0.2latest

---
name: google-skill
version: 1.0.2
url: https://clawskills.io/api/skills/google-skill/releases/1.0.2/SKILL.md
artifact_sha256: 99596749a9ca0603f591b6ab85a7461358898b09064a30007a9e412ab65668f6
signature: DVcOUSysZ8+Oaos7hEabG3TmIt+SGe8lLcfuRgZhCKfYTyBkBKknOyu558EZZWsNuyScEnOmsT7oKgdrmrRHAA==
key_id: 625b196966442b38cf1c7188ba15fa81
verify: https://clawskills.io/docs/verification
---
# Google Workspace Skill

Manage Gmail, Google Calendar, Drive, Docs, Sheets, Slides, Forms, Tasks, and Chat from an AI agent using the Google Workspace MCP Server.

---

## Overview
- **What it does:**
  Lets an AI agent interact with Google Workspace — search and send Gmail, manage calendar events, browse and edit Drive files, create and update Docs/Sheets/Slides, manage Forms and Tasks, and send Chat messages — using the `workspace-mcp` MCP server with OAuth 2.0 authentication.

- **When to use it:**
  When the user wants to automate Google Workspace tasks: searching emails, scheduling meetings, organizing Drive files, editing documents, analyzing spreadsheets, or managing tasks.

- **Requirements:**
  - OS: macOS / Linux / Windows
  - Runtime: Python 3.10+ (for `uvx`)
  - Accounts: Google account with OAuth 2.0 client credentials (client ID + client secret) from Google Cloud Console, with required APIs enabled

---

## Quick start

### Install

Add to your OpenClaw config (`~/.openclaw/openclaw.json`):

```json
{
  "mcpServers": {
    "google": {
      "command": "uvx",
      "args": ["workspace-mcp@1.11.1"]
    }
  }
}
```

To limit to specific services (recommended — least privilege):

```json
{
  "mcpServers": {
    "google": {
      "command": "uvx",
      "args": ["workspace-mcp@1.11.1", "--tools", "gmail", "drive", "calendar"]
    }
  }
}
```

For read-only access:

```json
{
  "mcpServers": {
    "google": {
      "command": "uvx",
      "args": ["workspace-mcp@1.11.1", "--read-only", "--tools", "gmail", "drive", "calendar"]
    }
  }
}
```

### Configure

Add your OAuth credentials in the **OpenClaw runtime environment** (Control UI env editor if available, process env, or `.env`):

```bash
# Required — set in OpenClaw runtime environment:
#   GOOGLE_OAUTH_CLIENT_ID      — OAuth 2.0 client ID from Google Cloud Console
#   GOOGLE_OAUTH_CLIENT_SECRET  — OAuth 2.0 client secret
#
# How to obtain:
#   1. Go to https://console.cloud.google.com/apis/credentials
#   2. Create an OAuth 2.0 Client ID (type: Desktop app)
#   3. Enable the APIs you need (Gmail, Calendar, Drive, Docs, Sheets, etc.)
#      at https://console.cloud.google.com/apis/library
#   4. On first use, the MCP server will prompt you to authorize via browser
```

### Verify

After connecting, ask your AI agent:

```text
List my 5 most recent Gmail messages
```

**Expected result:**
Returns a list of recent email subjects, senders, and dates from your Gmail inbox. On first use, you'll be prompted to authorize via browser.

---

## Core tasks

### Search Gmail

```text
Search Gmail for emails from alice@example.com in the last 7 days and summarize the subjects
```

Uses the `search_gmail_messages` tool with Gmail query syntax (e.g., `from:alice@example.com newer_than:7d`). Returns message IDs, subjects, senders, dates, and snippet previews.

### Read an email

```text
Show me the full content of the most recent email from alice@example.com
```

Uses `search_gmail_messages` to find the message, then `get_gmail_message_content` to retrieve the full body.

### Send an email

```text
Send an email to bob@example.com with subject "Meeting Notes" and body "Here are the notes from today's standup..."
```

Uses the `send_gmail_message` tool. The agent should always show you the full email (to, subject, body) and ask for confirmation before sending.

### Draft an email

```text
Draft an email to the team summarizing this week's progress, but don't send it yet
```

Uses the `draft_gmail_message` tool to create a draft in Gmail without sending.

### Manage calendar events

```text
List my Google Calendar events for the next 48 hours and flag any scheduling conflicts
```

Uses the `get_events` tool with a time range filter. Returns event titles, start/end times, attendees, and location.

### Create a calendar event

```text
Schedule a 30-minute meeting with alice@example.com tomorrow at 2pm titled "Project Sync"
```

Uses the `create_event` tool with title, start/end times, and attendee list.

### Check availability

```text
Check if I'm free between 2pm and 4pm next Tuesday
```

Uses the `query_freebusy` tool to check calendar availability for the specified time range.

### Browse Drive files

```text
Show files in my Google Drive modified in the last 3 days
```

Uses the `search_drive_files` tool with a `modifiedTime` query filter. Returns file names, MIME types, and last-modified timestamps.

### Edit a Google Doc

```text
Open the Google Doc titled "Q4 Planning" and append a section with today's meeting notes
```

Uses `search_docs` to find the document, then `modify_doc_text` to insert content.

### Analyze a spreadsheet

```text
Read the Google Sheet "Budget 2025" and summarize spending by category in the Expenses tab
```

Uses `read_sheet_values` with the spreadsheet ID and range. Returns cell values which the agent then aggregates.

### Create a task

```text
Create a new Google Task called "Review PR #42" with a due date of next Friday
```

Uses the `create_task` tool to add a task to the default task list.

---

## Available services and tools

The `workspace-mcp` server exposes tools organized by Google service. Use the `--tools` flag to enable only the services you need.

### Service names for `--tools` flag

```
gmail  drive  calendar  docs  sheets  slides  forms  tasks  contacts  chat  search  appscript
```

### Tool tiers

Control tool complexity with `--tool-tier`:

| Tier | Description |
|---|---|
| `core` | Essential operations: search, read, create, basic modify |
| `extended` | Core + management features: labels, folders, batch operations |
| `complete` | All tools: comments, headers/footers, publishing, admin |

Example with tier:

```json
{
  "mcpServers": {
    "google": {
      "command": "uvx",
      "args": ["workspace-mcp@1.11.1", "--tools", "gmail", "drive", "--tool-tier", "core"]
    }
  }
}
```

### Key tools by service

**Gmail** (15 tools): `search_gmail_messages`, `get_gmail_message_content`, `get_gmail_messages_content_batch`, `get_gmail_attachment_content`, `send_gmail_message`, `draft_gmail_message`, `get_gmail_thread_content`, `list_gmail_labels`, `manage_gmail_label`, `list_gmail_filters`, `create_gmail_filter`, `delete_gmail_filter`, `modify_gmail_message_labels`, `batch_modify_gmail_message_labels`

**Drive** (17 tools): `search_drive_files`, `get_drive_file_content`, `list_drive_items`, `create_drive_file`, `update_drive_file`, `copy_drive_file`, `get_drive_file_permissions`, `share_drive_file`, `batch_share_drive_file`, `update_drive_permission`, `remove_drive_permission`, `transfer_drive_ownership`, `get_drive_shareable_link`, `get_drive_file_download_url`, `check_drive_file_public_access`, `import_to_google_doc`, `set_drive_file_permissions`

**Calendar** (6 tools): `list_calendars`, `get_events`, `create_event`, `modify_event`, `delete_event`, `query_freebusy`

**Docs** (19 tools): `search_docs`, `get_doc_content`, `list_docs_in_folder`, `create_doc`, `modify_doc_text`, `find_and_replace_doc`, `insert_doc_elements`, `insert_doc_image`, `update_doc_headers_footers`, `batch_update_doc`, `inspect_doc_structure`, `create_table_with_data`, `export_doc_to_pdf`, `update_paragraph_style`, `read_doc_comments`, `create_doc_comment`, `reply_to_comment`, `resolve_comment`

**Sheets** (14 tools): `list_spreadsheets`, `get_spreadsheet_info`, `read_sheet_values`, `modify_sheet_values`, `format_sheet_range`, `add_conditional_formatting`, `create_spreadsheet`, `create_sheet`, `read_sheet_comments`, `create_sheet_comment`, `reply_to_sheet_comment`, `resolve_sheet_comment`

**Tasks** (12 tools): `list_task_lists`, `get_task_list`, `create_task_list`, `update_task_list`, `delete_task_list`, `list_tasks`, `get_task`, `create_task`, `update_task`, `delete_task`, `move_task`, `clear_completed_tasks`

**Slides** (4 tools): `create_presentation`, `get_presentation`, `add_slide`, `update_slide_content`

**Forms** (5 tools): `create_form`, `get_form`, `set_publish_settings`, `get_form_response`, `list_form_responses`

**Chat** (4 tools): `list_spaces`, `get_messages`, `send_message`, `search_messages`

---

## Environment variable contract

| Variable | Purpose | Required | Where to set |
|---|---|---|---|
| `GOOGLE_OAUTH_CLIENT_ID` | OAuth 2.0 client ID | Yes | OpenClaw runtime environment |
| `GOOGLE_OAUTH_CLIENT_SECRET` | OAuth 2.0 client secret | Yes | OpenClaw runtime environment |

Credentials are inherited by the MCP server process from the OpenClaw runtime environment.

---

## Configuration

* **Secrets / credentials required:**

  * `GOOGLE_OAUTH_CLIENT_ID` — from Google Cloud Console OAuth credentials
  * `GOOGLE_OAUTH_CLIENT_SECRET` — client secret for the OAuth app

* **How to obtain credentials:**

  1. Go to https://console.cloud.google.com/apis/credentials
  2. Create an OAuth 2.0 Client ID (application type: Desktop app)
  3. Enable the required APIs at https://console.cloud.google.com/apis/library:
     - Gmail API, Google Calendar API, Google Drive API, Google Docs API, Google Sheets API, etc.
  4. On first use, the MCP server will open a browser window for you to authorize
  5. After authorization, tokens are stored locally and refreshed automatically

* **Config files used:**

  * `~/.openclaw/openclaw.json` — MCP server configuration

* **How to reset / re-auth:**

  * Revoke app access at https://myaccount.google.com/permissions — find and remove the OAuth app
  * Delete the stored credentials directory at `~/.google_workspace_mcp/credentials`
  * Restart the MCP server to trigger a fresh authorization flow

---

## Security & Guardrails

### Secrets handling

* Never paste OAuth client secrets into chat.
* Always use environment variables for credential storage.
* The MCP server stores OAuth tokens locally at `~/.google_workspace_mcp/credentials` — treat this directory as sensitive.
* If authentication fails with a 401, revoke the existing token and re-authorize.

### Confirmations (before risky actions)

* Always confirm with the user before:
  * Sending emails (composing or replying on behalf of the user)
  * Deleting emails, calendar events, Drive files, or Docs
  * Sharing files or modifying permissions on Drive items
  * Creating or modifying calendar events that invite other people
  * Any action that modifies content visible to others
* The agent should present the planned action and target resource before executing.

### Data minimization

* Return summaries by default (subject lines, file names, event titles) — don't dump full email bodies or document contents.
* Limit list operations to reasonable page sizes (10-25 items).
* Avoid echoing personal email addresses in output unless necessary.
* Never log or display `GOOGLE_OAUTH_CLIENT_SECRET` values.

### Permissions / scopes

* **Use the `--tools` flag to enable only the services the user needs.** Don't enable all 12 services when the user only needs Gmail and Calendar.
* **Use the `--read-only` flag when write access isn't needed.** This restricts the server to read-only OAuth scopes and disables write tools.
* **Use `--tool-tier core` to minimize the number of available tools** unless the user needs advanced features.
* **Recommended: start with the narrowest configuration:**
  ```
  --read-only --tools gmail --tool-tier core
  ```
  Then expand as the user's needs grow.

### Network access

* **Domains used:**
  * `www.googleapis.com` — Google Workspace APIs (Gmail, Drive, Sheets, Docs, etc.)
  * `oauth2.googleapis.com` — OAuth token exchange
  * `accounts.google.com` — Google authentication

### Local storage

* **Writes to:** `~/.google_workspace_mcp/credentials` — cached OAuth tokens (auto-refreshed)
* **Path note:** Can be customized via `GOOGLE_MCP_CREDENTIALS_DIR` environment variable
* **Recovery:** Delete the credentials directory and re-authorize, or revoke at https://myaccount.google.com/permissions

### Revoke / rotate

* Revoke app access: https://myaccount.google.com/permissions — find and remove the OAuth app
* Rotate client secret: Google Cloud Console > APIs & Services > Credentials > edit the OAuth client > reset secret
* Delete the local token directory at `~/.google_workspace_mcp/credentials`
* Update environment variables with new client secret and re-authorize

---

## Troubleshooting

* **Error:** `401 Unauthorized` — invalid_client
  * Fix: The `GOOGLE_OAUTH_CLIENT_ID` or `GOOGLE_OAUTH_CLIENT_SECRET` is incorrect or the OAuth app has been deleted. Verify credentials in Google Cloud Console at https://console.cloud.google.com/apis/credentials.

* **Error:** `401 Unauthorized` — invalid_grant (Token has been expired or revoked)
  * Fix: Delete the stored credentials directory at `~/.google_workspace_mcp/credentials` and re-authorize by restarting the MCP server.

* **Error:** `403 Forbidden` — Access Not Configured
  * Fix: The required Google API is not enabled. Go to https://console.cloud.google.com/apis/library and enable the API (Gmail, Calendar, Drive, etc.) for your project.

* **Error:** `403 Forbidden` — Rate Limit Exceeded
  * Fix: You've hit the API quota. Wait and retry, or request a quota increase at https://console.cloud.google.com/apis/dashboard.

* **Problem:** "uvx command not found"
  * Fix: The `uvx` command requires Python package manager `uv` to be installed. Check that `uv` is on your PATH. OpenClaw requires `uv` for Python-based MCP servers.

* **Problem:** "Authorization flow not opening browser"
  * Fix: Ensure you have a browser available. If running headless, the server will print an authorization URL to the console — open it manually in any browser.

---

## Release notes

* v1.0.0:
  * Initial release
  * Google Workspace MCP Server (`workspace-mcp@1.11.1`)
  * Covers Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Tasks, Chat, Contacts, Search, Apps Script
  * OAuth 2.0 with built-in browser authorization flow

---

## Links

* Package (PyPI): https://pypi.org/project/workspace-mcp/
* GitHub: https://github.com/taylorwilsdon/google_workspace_mcp
* Documentation: https://workspacemcp.com/
* Google Cloud Console: https://console.cloud.google.com/apis/credentials
* Google APIs Library: https://console.cloud.google.com/apis/library
* Gmail API: https://developers.google.com/gmail/api
* Google Calendar API: https://developers.google.com/calendar
* Google Drive API: https://developers.google.com/drive

---

## Publisher

* **Publisher:** @Agentopolis