---
name: gspace
description: Use gspace CLI and MCP tools for Google Workspace operations (Drive, Gmail, Docs, Sheets, Calendar, Tasks). Use when working with Google Workspace URLs (docs.google.com, drive.google.com, sheets.google.com, slides.google.com, mail.google.com), Google Drive file IDs, or any Google Workspace file/email/calendar operations. Supports both CLI commands (via Bash) and 40+ MCP tools.
---
# Google Workspace (gspace) Skill

You are a Google Workspace specialist with access to both the **gspace CLI** (a command-line tool you can invoke via Bash) and **MCP (Model Context Protocol) tools**. This skill provides comprehensive guidance for working with Google Drive, Gmail, Docs, Sheets, Calendar, and Tasks operations through both interfaces.

**IMPORTANT:** gspace is a CLI tool installed on the system. Use it via the Bash tool with commands like `gspace drive files ls` or `gspace gmail search --query "subject:urgent"`. It is NOT only an MCP server.

## MCP vs CLI: When to Use Each

### Use MCP Tools When:
- **In conversation with user**: MCP tools are available directly in Claude Code sessions
- **Reading metadata**: Checking file properties, permissions, comments
- **Searching content**: Finding files, emails, calendar events, tasks
- **Retrieving information**: Getting email content, file metadata, calendar events
- **Quick lookups**: Fast, single-operation queries
- **Parsing Excel files**: Reading .xlsx file contents
- **Modifying content**: Creating, updating, deleting files, emails, tasks, calendar events

### Use CLI When:
- **Complex workflows**: Multi-step operations requiring scripting
- **Batch operations**: Processing multiple items with shell scripts
- **File uploads/downloads**: Transferring large files to/from local system
- **Interactive operations**: Authentication flows, confirmations
- **Shell automation**: Integration with other command-line tools

## Working with Google Docs/Sheets/Slides URLs

**IMPORTANT:** When the user provides a Google Workspace URL, you can use it directly with CLI commands or extract the file ID for MCP tools.

### CLI Commands for Downloading

**For Google Docs (markdown output):**
- **Recommended:** `gspace docs download FILE_ID /path/output.md` - Cleaner markdown output, handles multi-tab docs automatically, no embedded images by default
- **Alternative:** `gspace files download FILE_ID /path/output.md --export markdown` - Includes base64-encoded images inline, more verbose

**For format conversion:**
- Use `gspace files download FILE_ID /path/output.{pdf,docx,xlsx}` with `--export` flag (supports pdf, docx, xlsx, html, text, etc.)

**Important Notes:**
- `gspace files download` accepts file IDs (recommended) or full Google URLs (may fail with URL fragments)
- `gspace docs download` only accepts file IDs
- For cleaner, more readable markdown from Google Docs, prefer `gspace docs download`

### URL Patterns and File ID Extraction

**Google Docs:**
```
https://docs.google.com/document/d/FILE_ID/edit...
```

**Google Sheets:**
```
https://docs.google.com/spreadsheets/d/FILE_ID/edit...
```

**Google Slides:**
```
https://docs.google.com/presentation/d/FILE_ID/edit...
```

**Extraction:** The file ID is the long alphanumeric string between `/d/` and `/edit`

### Common URL Operations

**Example URL:** `https://docs.google.com/document/d/1711ddafVoaLzT8xPkL8RgqsJLY8HwzZqppxzWFjh0Gc/edit?tab=t.nlbxgkk0bjwu`
- **File ID:** `1711ddafVoaLzT8xPkL8RgqsJLY8HwzZqppxzWFjh0Gc`
- **Tab ID:** `t.nlbxgkk0bjwu` (optional, for multi-tab docs)

### Workflow: Fetch and Download from URL

```python
# 1. Extract file ID from URL
file_id = "1711ddafVoaLzT8xPkL8RgqsJLY8HwzZqppxzWFjh0Gc"

# 2. Get metadata to understand the file
metadata = mcp__gdrive__drive_files_metadata(file_id=file_id)
# Returns: name, mimeType, created/modified times

# 3. Download the file in desired format
mcp__gdrive__drive_files_download(
    file_id=file_id,
    local_path="/tmp/document.md",
    export_format="markdown"
)

# For multi-tab docs, specify tab_id
mcp__gdrive__drive_files_download(
    file_id=file_id,
    local_path="/tmp/specific_tab.md",
    export_format="markdown",
    tab_id="t.nlbxgkk0bjwu"
)
```

### Supported Export Formats

**Google Docs:**
- `markdown` - Best for readable text (recommended)
- `pdf` - Preserves formatting
- `docx` - Microsoft Word format
- `text` - Plain text only

**Google Sheets:**
- `xlsx` - Excel format (preserves all sheets and formulas)
- `csv` - Single sheet as CSV
- `pdf` - Printable format

**Google Slides:**
- `pdf` - Each slide as page
- `pptx` - Microsoft PowerPoint format

### URL-Based Workflows

**Workflow 1: Read Doc from URL**
```python
# User provides: https://docs.google.com/document/d/ABC123/edit
file_id = "ABC123"

# Download and read
mcp__gdrive__drive_files_download(
    file_id=file_id,
    local_path="/tmp/doc.md",
    export_format="markdown"
)
# Then read /tmp/doc.md using Read tool
```

**Workflow 2: Comment on Doc from URL**
```python
# Add comment to document
mcp__gdrive__docs_comments_create(
    file_id="ABC123",
    content="This section needs updating"
)
```

**Workflow 3: Share Doc from URL**
```python
# Grant access to document
mcp__gdrive__permissions_grant(
    file_id="ABC123",
    role="reader",
    type="user",
    email="colleague@example.com"
)
```

**Workflow 4: Parse Sheet from URL**
```python
# For Google Sheets saved as .xlsx in Drive
file_id = "SHEET123"

# If it's a Google Sheet, download as xlsx first
mcp__gdrive__drive_files_download(
    file_id=file_id,
    local_path="/tmp/sheet.xlsx",
    export_format="xlsx"
)

# Then parse the .xlsx file
# (Note: For native Google Sheets, use sheets_* tools instead)
```

## MCP Tools Complete Reference

### Authentication Tools

#### `mcp__gdrive__drive_check_auth`
Verify Google Drive authentication status and OAuth scopes.

```python
# No parameters required
mcp__gdrive__drive_check_auth()
```

**Returns:** Authentication status with account info and required scopes

**Use cases:**
- Verify authentication before file operations
- Diagnose access issues
- Confirm token validity

#### `mcp__gdrive__gmail_check_auth`
Verify Gmail API authentication and required scopes.

```python
mcp__gdrive__gmail_check_auth()
```

#### `mcp__gdrive__calendar_check_auth`
Verify Calendar API authentication and required scopes.

```python
mcp__gdrive__calendar_check_auth()
```

### Google Drive File Operations

#### `mcp__gdrive__drive_files_list`
List files with advanced filtering (owner, dates, type, folder).

**Parameters:**
- `query` (string, optional): Search query for file names
- `type` (string, optional): MIME type filter
- `folder` (string, optional): Search within specific folder ID
- `owner` (string, optional): Filter by file owner email
- `created_after` (string, optional): ISO date (YYYY-MM-DD)
- `created_before` (string, optional): ISO date
- `modified_after` (string, optional): ISO date
- `modified_before` (string, optional): ISO date
- `order_by` (string, optional): Sort order (e.g., "modifiedTime desc")
- `limit` (number, optional): Max results (1-100, default: 10)

```python
# Search by filename
mcp__gdrive__drive_files_list(query="report", limit=20)

# Search by owner and date
mcp__gdrive__drive_files_list(
    owner="user@example.com",
    modified_after="2025-01-01",
    order_by="modifiedTime desc"
)
```

#### `mcp__gdrive__drive_files_download`
Download file with format conversion (PDF, DOCX, XLSX, markdown).

**Parameters:**
- `file_id` (string, required): Google Drive file ID
- `local_path` (string, required): Local file system path
- `export_format` (string, optional): Export format (text, csv, xlsx, pdf, docx, markdown)
- `tab_id` (string, optional): Specific tab ID for multi-tab Docs
- `max_size` (number, optional): Max file size in bytes
- `timeout` (number, optional): Download timeout in milliseconds

```python
# Download Google Doc as markdown
mcp__gdrive__drive_files_download(
    file_id="abc123",
    local_path="/tmp/document.md",
    export_format="markdown"
)

# Download Google Sheet as Excel (preserves all sheets)
mcp__gdrive__drive_files_download(
    file_id="sheet123",
    local_path="/tmp/data.xlsx",
    export_format="xlsx"
)
```

#### `mcp__gdrive__drive_files_upload`
Upload local files with automatic CSV→Sheets conversion.

**Parameters:**
- `local_path` (string, required): Path to local file
- `name` (string, optional): Name in Drive (defaults to filename)
- `parent_folder_id` (string, optional): Parent folder ID
- `description` (string, optional): File description
- `convert_to_google_format` (boolean, optional): Convert CSV to Sheets
- `mime_type` (string, optional): MIME type (auto-detected)

```python
# Upload CSV and convert to Google Sheet
mcp__gdrive__drive_files_upload(
    local_path="/tmp/data.csv",
    name="Sales Data 2025",
    convert_to_google_format=True
)
```

#### `mcp__gdrive__drive_files_copy`
Create file/folder copies with optional renaming.

**Parameters:**
- `file_id` (string, required): ID of file to copy
- `name` (string, optional): Name for copy
- `parent_folder_id` (string, optional): Destination folder

```python
mcp__gdrive__drive_files_copy(
    file_id="abc123",
    name="Backup Copy",
    parent_folder_id="folder456"
)
```

#### `mcp__gdrive__drive_files_rename`
Rename files and folders.

**Parameters:**
- `file_id` (string, required): ID of file to rename
- `name` (string, required): New name

```python
mcp__gdrive__drive_files_rename(
    file_id="abc123",
    name="Updated Document Name"
)
```

#### `mcp__gdrive__drive_files_delete`
Delete files/folders (trash or permanent).

**Parameters:**
- `file_id` (string, required): ID of file to delete
- `permanently` (boolean, optional): Permanent delete vs trash (default: false)

```python
# Move to trash
mcp__gdrive__drive_files_delete(file_id="abc123")

# Permanently delete
mcp__gdrive__drive_files_delete(file_id="abc123", permanently=True)
```

#### `mcp__gdrive__drive_files_metadata`
Get comprehensive file metadata.

**Parameters:**
- `file_id` (string, required): File ID

```python
mcp__gdrive__drive_files_metadata(file_id="abc123")
```

**Returns:** Name, size, mimeType, created/modified times, owner, sharing settings

#### `mcp__gdrive__drive_files_validate_markdown`
Validate Google Docs export to markdown compatibility.

**Parameters:**
- `file_id` (string, required): Google Doc file ID

```python
mcp__gdrive__drive_files_validate_markdown(file_id="doc123")
```

**Returns:** Compatibility score and recommendations

#### `mcp__gdrive__drive_files_list_tabs`
List all tabs in a Google Doc (experimental API).

**Parameters:**
- `file_id` (string, required): Google Doc file ID

```python
mcp__gdrive__drive_files_list_tabs(file_id="doc123")
```

### Google Drive Folder Operations

#### `mcp__gdrive__drive_folders_create`
Create folders with optional descriptions.

**Parameters:**
- `name` (string, required): Folder name
- `parent_folder_id` (string, optional): Parent folder ID
- `description` (string, optional): Folder description

```python
mcp__gdrive__drive_folders_create(
    name="Project Documents",
    description="All project files"
)
```

#### `mcp__gdrive__drive_folders_move`
Move files/folders between locations.

**Parameters:**
- `file_id` (string, required): ID of file/folder to move
- `new_parent_folder_id` (string, required): Destination folder ID
- `remove_from_current_parents` (boolean, optional): Remove from current parents (default: true)

```python
mcp__gdrive__drive_folders_move(
    file_id="abc123",
    new_parent_folder_id="folder456"
)
```

### Permissions Management

#### `mcp__gdrive__permissions_grant`
Grant user/group/domain access to files.

**Parameters:**
- `file_id` (string, required): File ID
- `role` (string, required): reader, writer, commenter, owner
- `type` (string, required): user, group, domain, anyone
- `email` (string, optional): Email address (for user/group)
- `domain` (string, optional): Domain name or "current"

```python
# Grant write access to user
mcp__gdrive__permissions_grant(
    file_id="abc123",
    role="writer",
    type="user",
    email="user@example.com"
)

# Share with entire domain
mcp__gdrive__permissions_grant(
    file_id="abc123",
    role="reader",
    type="domain",
    domain="current"
)
```

#### `mcp__gdrive__permissions_list`
List current file/folder permissions.

**Parameters:**
- `file_id` (string, required): File ID

```python
mcp__gdrive__permissions_list(file_id="abc123")
```

**Returns:** List of permissions with roles and email addresses

#### `mcp__gdrive__permissions_update`
Modify existing permission roles.

**Parameters:**
- `file_id` (string, required): File ID
- `permission_id` (string, required): Permission ID
- `role` (string, required): New role (reader, writer, commenter)

```python
mcp__gdrive__permissions_update(
    file_id="abc123",
    permission_id="perm456",
    role="commenter"
)
```

#### `mcp__gdrive__permissions_revoke`
Remove user/group access.

**Parameters:**
- `file_id` (string, required): File ID
- `permission_id` (string, required): Permission ID to remove

```python
mcp__gdrive__permissions_revoke(
    file_id="abc123",
    permission_id="perm456"
)
```

### Google Docs Operations

#### `mcp__gdrive__docs_create`
Create Google Docs from markdown files.

**Parameters:**
- `local_path` (string, required): Path to markdown file
- `name` (string, required): Document name
- `parent_folder_id` (string, optional): Parent folder ID

```python
mcp__gdrive__docs_create(
    local_path="/tmp/notes.md",
    name="Meeting Notes",
    parent_folder_id="folder123"
)
```

#### `mcp__gdrive__docs_download`
Download Docs as markdown with footnote conversion.

**Parameters:**
- `file_id` (string, required): Google Doc file ID
- `local_path` (string, required): Output path
- `export_format` (string, optional): Export format (markdown, pdf, docx)

```python
mcp__gdrive__docs_download(
    file_id="doc123",
    local_path="/tmp/document.md",
    export_format="markdown"
)
```

#### `mcp__gdrive__docs_apply_text_diff`
Update document content remotely without downloading.

**Parameters:**
- `file_id` (string, required): Google Doc file ID
- `new_content` (string, required): New text content
- `preserve_formatting` (boolean, optional): Keep formatting (default: true)

```python
mcp__gdrive__docs_apply_text_diff(
    file_id="doc123",
    new_content="Updated document text...",
    preserve_formatting=True
)
```

#### `mcp__gdrive__docs_find_replace`
Find and replace text with case-sensitive/insensitive matching.

**Parameters:**
- `file_id` (string, required): Google Doc file ID
- `find_text` (string, required): Text to find
- `replace_text` (string, required): Replacement text
- `match_case` (boolean, optional): Case-sensitive (default: false)
- `tab_id` (string, optional): Specific tab ID

```python
# Case-insensitive replacement
mcp__gdrive__docs_find_replace(
    file_id="doc123",
    find_text="TODO",
    replace_text="DONE"
)

# Case-sensitive replacement
mcp__gdrive__docs_find_replace(
    file_id="doc123",
    find_text="Error",
    replace_text="Warning",
    match_case=True
)
```

### Google Docs Comments

#### `mcp__gdrive__docs_comments_list`
List all comments on a document.

**Parameters:**
- `file_id` (string, required): File ID
- `include_deleted` (boolean, optional): Include deleted comments
- `page_size` (number, optional): Results per page (1-100)
- `page_token` (string, optional): Pagination token

```python
mcp__gdrive__docs_comments_list(
    file_id="doc123",
    page_size=50
)
```

#### `mcp__gdrive__docs_comments_get`
Get specific comment details.

**Parameters:**
- `file_id` (string, required): File ID
- `comment_id` (string, required): Comment ID
- `include_deleted` (boolean, optional): Include deleted replies

```python
mcp__gdrive__docs_comments_get(
    file_id="doc123",
    comment_id="comment456"
)
```

#### `mcp__gdrive__docs_comments_create`
Add new comments to documents.

**Parameters:**
- `file_id` (string, required): File ID
- `content` (string, required): Comment text
- `anchor` (string, optional): Anchor region for specific text

```python
# General comment
mcp__gdrive__docs_comments_create(
    file_id="doc123",
    content="Please review this section"
)
```

#### `mcp__gdrive__docs_comments_reply`
Reply to existing comments.

**Parameters:**
- `file_id` (string, required): File ID
- `comment_id` (string, required): Comment ID
- `content` (string, required): Reply text
- `action` (string, optional): "resolve" or "reopen"

```python
# Reply and resolve
mcp__gdrive__docs_comments_reply(
    file_id="doc123",
    comment_id="comment456",
    content="Fixed, thanks!",
    action="resolve"
)
```

#### `mcp__gdrive__docs_comments_resolve`
Mark comment as resolved.

**Parameters:**
- `file_id` (string, required): File ID
- `comment_id` (string, required): Comment ID

```python
mcp__gdrive__docs_comments_resolve(
    file_id="doc123",
    comment_id="comment456"
)
```

### Google Sheets Operations

#### `mcp__gdrive__sheets_create`
Create sheets with initial headers and data.

**Parameters:**
- `name` (string, required): Spreadsheet name
- `parent_folder_id` (string, optional): Parent folder ID
- `headers` (array, optional): Column headers
- `data` (2D array, optional): Initial data rows

```python
mcp__gdrive__sheets_create(
    name="Customer Database",
    headers=["Name", "Email", "Status"],
    data=[
        ["John Doe", "john@example.com", "Active"],
        ["Jane Smith", "jane@example.com", "Pending"]
    ]
)
```

#### `mcp__gdrive__sheets_update`
Modify specific cells using A1 notation with formula support.

**Parameters:**
- `file_id` (string, required): Spreadsheet ID
- `range` (string, required): A1 notation (e.g., "Sheet1!A1:C3")
- `values` (2D array, required): Cell values
- `input_option` (string, optional): "RAW" or "USER_ENTERED" (default)

```python
# Update with formulas
mcp__gdrive__sheets_update(
    file_id="sheet123",
    range="A1:B2",
    values=[
        ["Product", "Price"],
        ["Widget", "=SUM(B3:B10)"]
    ],
    input_option="USER_ENTERED"
)
```

#### `mcp__gdrive__sheets_append`
Append rows to end of data without range calculation.

**Parameters:**
- `file_id` (string, required): Spreadsheet ID
- `values` (2D array, required): Rows to append
- `range` (string, optional): Starting range (default: "Sheet1!A1")
- `input_option` (string, optional): "RAW" or "USER_ENTERED"

```python
mcp__gdrive__sheets_append(
    file_id="sheet123",
    values=[
        ["New Customer", "new@example.com", "Active"],
        ["Another Customer", "another@example.com", "Pending"]
    ]
)
```

### Google Calendar Operations

#### `mcp__gdrive__calendar_list`
List events with time range filtering and privacy controls.

**Parameters:**
- `calendar_id` (string, optional): Calendar ID (default: "primary")
- `time_min` (string, optional): Start time (RFC3339 format)
- `time_max` (string, optional): End time (RFC3339 format)
- `max_results` (number, optional): Max events (1-2500, default: 50)
- `page_token` (string, optional): Pagination token
- `single_events` (boolean, optional): Expand recurring events (default: true)
- `include_attendees` (boolean, optional): Include attendees (default: false)
- `include_description` (boolean, optional): Include description (default: false)
- `include_location` (boolean, optional): Include location (default: false)

```python
# List this month's events
mcp__gdrive__calendar_list(
    time_min="2025-01-01T00:00:00Z",
    time_max="2025-01-31T23:59:59Z",
    max_results=50
)
```

#### `mcp__gdrive__calendar_search`
Search events by text query with advanced filters.

**Parameters:**
- `q` (string, optional): Free-text search query
- `calendar_id` (string, optional): Calendar ID (default: "primary")
- `time_min` (string, optional): Start time
- `time_max` (string, optional): End time
- `max_results` (number, optional): Max results (1-2500)

```python
mcp__gdrive__calendar_search(
    q="team meeting",
    time_min="2025-01-01T00:00:00Z",
    max_results=10
)
```

#### `mcp__gdrive__calendar_create`
Create events with recurrence support.

**Parameters:**
- `summary` (string, required): Event title
- `start` (string, required): Start time (RFC3339)
- `end` (string, required): End time (RFC3339)
- `calendar_id` (string, optional): Calendar ID
- `description` (string, optional): Event description
- `location` (string, optional): Event location
- `recurrence` (object, optional): Recurrence pattern

```python
# Create single event
mcp__gdrive__calendar_create(
    summary="Sprint Planning",
    start="2025-11-10T14:00:00Z",
    end="2025-11-10T15:00:00Z"
)

# Create recurring event
mcp__gdrive__calendar_create(
    summary="Daily Standup",
    start="2025-11-10T09:00:00Z",
    end="2025-11-10T09:15:00Z",
    recurrence={"frequency": "daily", "count": 30}
)
```

#### `mcp__gdrive__calendar_update`
Modify existing calendar events.

**Parameters:**
- `event_id` (string, required): Event ID
- `calendar_id` (string, optional): Calendar ID
- `summary` (string, optional): New title
- `start` (string, optional): New start time
- `end` (string, optional): New end time
- `description` (string, optional): New description

```python
mcp__gdrive__calendar_update(
    event_id="event123",
    summary="Updated Meeting Title",
    start="2025-11-10T15:00:00Z"
)
```

#### `mcp__gdrive__calendar_delete`
Remove events from calendar.

**Parameters:**
- `event_id` (string, required): Event ID
- `calendar_id` (string, optional): Calendar ID

```python
mcp__gdrive__calendar_delete(event_id="event123")
```

#### `mcp__gdrive__calendar_update_reminders`
Modify event reminder settings.

**Parameters:**
- `event_id` (string, required): Event ID
- `calendar_id` (string, optional): Calendar ID
- `use_default` (boolean, required): Use calendar defaults
- `overrides` (array, optional): Custom reminders (method, minutes)
- `send_updates` (string, optional): "none", "all", "externalOnly"

```python
# Disable all reminders
mcp__gdrive__calendar_update_reminders(
    event_id="event123",
    use_default=False,
    overrides=[]
)

# Set custom reminders
mcp__gdrive__calendar_update_reminders(
    event_id="event123",
    use_default=False,
    overrides=[
        {"method": "popup", "minutes": 10},
        {"method": "email", "minutes": 60}
    ]
)
```

### Gmail Operations

#### `mcp__gdrive__gmail_search`
Search messages with advanced query syntax.

**Parameters:**
- `query` (string, required): Gmail search query
- `max_results` (number, optional): Max messages to return

```python
# Search by sender and subject
mcp__gdrive__gmail_search(
    query="from:boss@company.com subject:urgent",
    max_results=10
)

# Search for attachments
mcp__gdrive__gmail_search(
    query="has:attachment after:2025/01/01"
)
```

#### `mcp__gdrive__gmail_get`
Get full message content with headers.

**Parameters:**
- `message_id` (string, required): Gmail message ID

```python
mcp__gdrive__gmail_get(message_id="msg123")
```

**Returns:** Complete message with headers, body, attachments metadata

#### `mcp__gdrive__gmail_thread`
Get entire conversation thread.

**Parameters:**
- `thread_id` (string, required): Gmail thread ID

```python
mcp__gdrive__gmail_thread(thread_id="thread123")
```

#### `mcp__gdrive__gmail_send`
Send new messages with attachments.

**Parameters:**
- `to` (string, required): Recipient email(s)
- `subject` (string, required): Email subject
- `body` (string, required): Message body
- `cc` (string, optional): CC recipients
- `bcc` (string, optional): BCC recipients
- `attachments` (array, optional): File paths to attach

```python
mcp__gdrive__gmail_send(
    to="user@example.com",
    subject="Project Update",
    body="Please find the attached report.",
    attachments=["/tmp/report.pdf"]
)
```

#### `mcp__gdrive__gmail_draft`
Create draft messages.

**Parameters:**
- `to` (string, required): Recipient email
- `subject` (string, required): Email subject
- `body` (string, required): Message body

```python
mcp__gdrive__gmail_draft(
    to="team@example.com",
    subject="Draft: Review Request",
    body="Please review this document..."
)
```

#### `mcp__gdrive__gmail_send_draft`
Send existing drafts.

**Parameters:**
- `draft_id` (string, required): Draft ID

```python
mcp__gdrive__gmail_send_draft(draft_id="draft123")
```

#### `mcp__gdrive__gmail_list_labels`
List all Gmail labels.

```python
# No parameters required
mcp__gdrive__gmail_list_labels()
```

#### `mcp__gdrive__gmail_label`
Add/remove labels on messages.

**Parameters:**
- `message_id` (string, required): Message ID
- `add_labels` (array, optional): Labels to add
- `remove_labels` (array, optional): Labels to remove

```python
mcp__gdrive__gmail_label(
    message_id="msg123",
    add_labels=["IMPORTANT"],
    remove_labels=["INBOX"]
)
```

#### `mcp__gdrive__gmail_archive`
Archive messages (remove from inbox).

**Parameters:**
- `message_id` (string, required): Message ID

```python
mcp__gdrive__gmail_archive(message_id="msg123")
```

#### `mcp__gdrive__gmail_star`
Star/unstar messages.

**Parameters:**
- `message_id` (string, required): Message ID
- `unstar` (boolean, optional): Unstar message (default: false)

```python
# Star message
mcp__gdrive__gmail_star(message_id="msg123")

# Unstar message
mcp__gdrive__gmail_star(message_id="msg123", unstar=True)
```

#### `mcp__gdrive__gmail_trash`
Move messages to trash.

**Parameters:**
- `message_id` (string, required): Message ID

```python
mcp__gdrive__gmail_trash(message_id="msg123")
```

#### `mcp__gdrive__gmail_delete`
Permanently delete messages.

**Parameters:**
- `message_id` (string, required): Message ID

```python
mcp__gdrive__gmail_delete(message_id="msg123")
```

#### `mcp__gdrive__gmail_download_attachment`
Download message attachments.

**Parameters:**
- `message_id` (string, required): Message ID
- `attachment_id` (string, required): Attachment ID
- `output_path` (string, required): Local output path

```python
mcp__gdrive__gmail_download_attachment(
    message_id="msg123",
    attachment_id="attach456",
    output_path="/tmp/document.pdf"
)
```

### Google Tasks Operations

#### `mcp__gdrive__tasks_list_lists`
List all task lists.

```python
# No parameters required
mcp__gdrive__tasks_list_lists()
```

#### `mcp__gdrive__tasks_get_list`
Get specific task list details.

**Parameters:**
- `task_list_id` (string, required): Task list ID

```python
mcp__gdrive__tasks_get_list(task_list_id="list123")
```

#### `mcp__gdrive__tasks_list`
List tasks in a task list.

**Parameters:**
- `task_list_id` (string, required): Task list ID
- `show_completed` (boolean, optional): Include completed tasks
- `show_deleted` (boolean, optional): Include deleted tasks
- `show_hidden` (boolean, optional): Include hidden tasks

```python
mcp__gdrive__tasks_list(
    task_list_id="list123",
    show_completed=True
)
```

#### `mcp__gdrive__tasks_get`
Get specific task details.

**Parameters:**
- `task_list_id` (string, required): Task list ID
- `task_id` (string, required): Task ID

```python
mcp__gdrive__tasks_get(
    task_list_id="list123",
    task_id="task456"
)
```

#### `mcp__gdrive__tasks_create_list`
Create new task lists.

**Parameters:**
- `title` (string, required): Task list title

```python
mcp__gdrive__tasks_create_list(title="Q1 Goals")
```

#### `mcp__gdrive__tasks_create`
Create new tasks with due dates.

**Parameters:**
- `task_list_id` (string, required): Task list ID
- `title` (string, required): Task title
- `notes` (string, optional): Task notes
- `due` (string, optional): Due date (RFC3339)
- `parent` (string, optional): Parent task ID

```python
mcp__gdrive__tasks_create(
    task_list_id="list123",
    title="Review PR #42",
    due="2025-11-10T17:00:00Z",
    notes="High priority"
)
```

#### `mcp__gdrive__tasks_update`
Modify existing tasks.

**Parameters:**
- `task_list_id` (string, required): Task list ID
- `task_id` (string, required): Task ID
- `title` (string, optional): New title
- `notes` (string, optional): New notes
- `due` (string, optional): New due date
- `status` (string, optional): "needsAction" or "completed"

```python
mcp__gdrive__tasks_update(
    task_list_id="list123",
    task_id="task456",
    title="Updated Task Title",
    status="completed"
)
```

#### `mcp__gdrive__tasks_complete`
Mark tasks as completed.

**Parameters:**
- `task_list_id` (string, required): Task list ID
- `task_id` (string, required): Task ID

```python
mcp__gdrive__tasks_complete(
    task_list_id="list123",
    task_id="task456"
)
```

#### `mcp__gdrive__tasks_delete`
Delete tasks.

**Parameters:**
- `task_list_id` (string, required): Task list ID
- `task_id` (string, required): Task ID

```python
mcp__gdrive__tasks_delete(
    task_list_id="list123",
    task_id="task456"
)
```

#### `mcp__gdrive__tasks_clear_completed`
Clear all completed tasks from a list.

**Parameters:**
- `task_list_id` (string, required): Task list ID

```python
mcp__gdrive__tasks_clear_completed(task_list_id="list123")
```

### XLSX File Operations

#### `mcp__gdrive__parse_xlsx`
Parse Excel (.xlsx) file contents.

**Parameters:**
- `file_id` (string, required): Google Drive file ID of .xlsx file

```python
mcp__gdrive__parse_xlsx(file_id="spreadsheet123")
```

**Returns:** Structured data from Excel file (sheets, rows, columns)

#### `mcp__gdrive__write_xlsx`
Create XLSX file from JSON workbook structure.

**Parameters:**
- `workbook` (object, required): Workbook structure with sheets array
- `file_path` (string, required): Absolute path where XLSX should be created

```python
mcp__gdrive__write_xlsx(
    workbook={
        "sheets": [
            {
                "name": "Q1 Budget",
                "data": [
                    ["Category", "Amount"],
                    ["Salaries", 150000],
                    ["Marketing", 75000]
                ],
                "formulas": {
                    "B4": "=SUM(B2:B3)"
                }
            }
        ]
    },
    file_path="/tmp/output.xlsx"
)
```

## CLI Operations Reference

### Authentication

```bash
# Check authentication status
gspace auth check

# Login (interactive)
gspace auth login
```

### Drive File Operations

```bash
# List files
gspace drive files ls
gspace drive files ls --owner user@example.com --limit 20

# Download files (accepts file IDs or full Google URLs)
gspace files download FILE_ID /tmp/document.pdf
gspace files download FILE_ID_OR_URL /tmp/doc.md --export markdown
gspace files download "https://docs.google.com/document/d/FILE_ID/edit" /tmp/doc.md --export markdown
gspace files download FILE_ID /tmp/sheet.xlsx --export xlsx

# Upload files
gspace drive files upload /path/to/file "File Name"
gspace drive files upload data.csv "Spreadsheet" --convert

# Copy, rename, delete
gspace drive files copy FILE_ID --name "Copy of Document"
gspace drive files rename FILE_ID "New Name"
gspace drive files delete FILE_ID

# Get metadata
gspace drive files metadata FILE_ID
```

### Drive Folders

```bash
# Create folder
gspace drive folders create "Project Documents"

# Move file to folder
gspace drive folders move FILE_ID FOLDER_ID
```

### Permissions

```bash
# Grant permission
gspace permissions grant FILE_ID --type user --role writer --email user@example.com
gspace permissions grant FILE_ID --type domain --role reader --domain current

# List permissions
gspace permissions list FILE_ID

# Update permission
gspace permissions update FILE_ID PERMISSION_ID --role commenter

# Revoke permission
gspace permissions revoke FILE_ID PERMISSION_ID
```

### Google Docs

```bash
# Create doc from markdown
gspace docs create /path/to/notes.md "Document Title"

# Download doc as markdown (specialized command, auto-handles single/multi-tab docs)
gspace docs download DOC_ID /tmp/output.md
gspace docs download DOC_ID /tmp/output.md --include-images

# Download doc with format conversion (use files download for format control)
gspace files download DOC_ID /tmp/output.md --export markdown
gspace files download DOC_ID /tmp/output.pdf --export pdf
gspace files download DOC_ID /tmp/output.docx --export docx

# Find and replace
gspace docs find-replace DOC_ID "old text" "new text"
gspace docs find-replace DOC_ID "Error" "Warning" --match-case

# Comments
gspace docs comments list DOC_ID
gspace docs comments create DOC_ID "Great work!"
gspace docs comments reply DOC_ID COMMENT_ID "Thanks!"
gspace docs comments resolve DOC_ID COMMENT_ID
```

### Google Sheets

```bash
# Create sheet
gspace sheets create "Sales Data" --headers "Product,Price,Quantity"

# Update cells
gspace sheets update SHEET_ID --range "A1:B2" --values '[["Name","Value"],["Item",100]]'

# Append rows
gspace sheets append SHEET_ID --values '[["New Row 1","Value 1"]]'
```

### Google Calendar

```bash
# List events
gspace calendar list --time-min 2025-01-01T00:00:00Z
gspace calendar today
gspace calendar tomorrow

# Search events
gspace calendar search --query "team meeting"

# Create event
gspace calendar create "Sprint Planning" --start "2025-11-10T14:00:00Z" --end "2025-11-10T15:00:00Z"

# Update/delete events
gspace calendar update EVENT_ID --summary "New Title"
gspace calendar delete EVENT_ID

# Update reminders
gspace calendar update-reminders EVENT_ID --disable
```

### Gmail

```bash
# Search emails
gspace gmail search --query "from:boss@company.com subject:urgent"

# Get message/thread
gspace gmail get MESSAGE_ID
gspace gmail thread THREAD_ID

# Send email
gspace gmail send --to user@example.com --subject "Hello" --body "Message"
gspace gmail send --to user@example.com --subject "Report" --attach report.pdf

# Draft management
gspace gmail draft --to team@example.com --subject "Review"
gspace gmail send-draft DRAFT_ID

# Message management
gspace gmail archive MESSAGE_ID
gspace gmail star MESSAGE_ID
gspace gmail trash MESSAGE_ID
gspace gmail delete MESSAGE_ID
gspace gmail label MESSAGE_ID --add IMPORTANT --remove INBOX

# Labels
gspace gmail list-labels

# Download attachment
gspace gmail download-attachment MESSAGE_ID ATTACHMENT_ID /tmp/file.pdf
```

### Google Tasks

```bash
# List task lists
gspace tasks list-lists

# List tasks
gspace tasks list TASK_LIST_ID
gspace tasks list TASK_LIST_ID --show-completed

# Create task
gspace tasks create TASK_LIST_ID "Review PR" --due "2025-11-10T17:00:00Z"

# Update/complete/delete task
gspace tasks update TASK_LIST_ID TASK_ID --title "Updated Title"
gspace tasks complete TASK_LIST_ID TASK_ID
gspace tasks delete TASK_LIST_ID TASK_ID

# Clear completed
gspace tasks clear-completed TASK_LIST_ID
```

## Common Workflows

### Workflow 1: Find and Download Documents (MCP)

```python
# 1. Search for documents
files = mcp__gdrive__drive_files_list(
    query="Q4 report",
    type="application/vnd.google-apps.document",
    limit=10
)

# 2. Download as markdown
mcp__gdrive__drive_files_download(
    file_id=files[0].id,
    local_path="/tmp/report.md",
    export_format="markdown"
)
```

### Workflow 2: Email Task Management (MCP)

```python
# 1. Search for emails with actionable items
messages = mcp__gdrive__gmail_search(
    query="subject:TODO is:unread",
    max_results=20
)

# 2. Create tasks from emails
for message in messages:
    email = mcp__gdrive__gmail_get(message_id=message.id)

    # Create task
    mcp__gdrive__tasks_create(
        task_list_id="default",
        title=f"Follow up: {email.subject}",
        notes=email.snippet
    )

    # Archive email
    mcp__gdrive__gmail_archive(message_id=message.id)
```

### Workflow 3: Calendar Event Cleanup (MCP)

```python
# 1. Search for "do not block" events
events = mcp__gdrive__calendar_search(
    q="do not block",
    time_min="2025-01-01T00:00:00Z"
)

# 2. Disable reminders for each event
for event in events:
    mcp__gdrive__calendar_update_reminders(
        event_id=event.id,
        use_default=False,
        overrides=[]
    )
```

### Workflow 4: Bulk File Permissions (CLI)

```bash
# Share all PDFs in folder with team
gspace drive files ls --folder-id FOLDER_ID --type application/pdf --json | \
  jq -r '.[].id' | \
  while read file_id; do
    gspace permissions grant "$file_id" --type domain --role reader --domain current
  done
```

### Workflow 5: Email Backup (CLI)

```bash
# Download all attachments from specific sender
gspace gmail search --query "from:vendor@example.com has:attachment" --json | \
  jq -r '.[].id' | \
  while read msg_id; do
    gspace gmail get "$msg_id" --json | \
      jq -r '.attachments[].id' | \
      while read attach_id; do
        gspace gmail download-attachment "$msg_id" "$attach_id" "/tmp/backup_${attach_id}.pdf"
      done
  done
```

## Best Practices

### General Principles

1. **Prefer MCP for programmatic operations**: MCP tools provide structured responses
2. **Use CLI for interactive workflows**: Better for shell scripts and automation
3. **Batch operations carefully**: Use pagination and limits to avoid overwhelming responses
4. **Check authentication first**: Use `*_check_auth` tools before operations
5. **Handle errors gracefully**: All MCP tools return error details in responses

### MCP-Specific Best Practices

1. **Use appropriate limits**: Set `limit` or `max_results` to avoid large responses
2. **Leverage filters**: Use owner, date, type filters to narrow searches
3. **Parse responses**: All MCP tools return structured JSON
4. **Privacy controls**: Use calendar privacy flags to minimize PII exposure
5. **Pagination**: Use `page_token` for large result sets

### CLI-Specific Best Practices

1. **JSON output for scripting**: Use `--json` flag with `jq` for processing
2. **Confirm destructive operations**: CLI prompts for confirmations by default
3. **Use environment variables**: Set `GOOGLE_CLOUD_PROJECT` for quota management
4. **Batch with shell loops**: Combine CLI with shell scripts for bulk operations

## Search Query Syntax

### Drive Queries

- `name contains 'text'` - Search by filename
- `fullText contains 'text'` - Search file contents
- `mimeType = 'application/pdf'` - Filter by file type
- `'folder-id' in parents` - Files in specific folder
- `trashed = false` - Exclude trashed files
- `modifiedTime > '2025-01-01T00:00:00'` - Modified after date

**Common MIME types:**
- Google Docs: `application/vnd.google-apps.document`
- Google Sheets: `application/vnd.google-apps.spreadsheet`
- Google Slides: `application/vnd.google-apps.presentation`
- PDF: `application/pdf`

### Gmail Queries

- `from:sender@example.com` - From specific sender
- `to:recipient@example.com` - To specific recipient
- `subject:keyword` - Subject contains keyword
- `has:attachment` - Has attachments
- `filename:pdf` - Specific attachment type
- `after:2025/01/01` - Date filters
- `before:2025/12/31` - Date filters
- `is:unread` - Unread messages
- `is:starred` - Starred messages
- `label:IMPORTANT` - Specific label

## Error Handling

### Common Errors

**Authentication Errors:**
```python
# Check auth status
mcp__gdrive__drive_check_auth()
```

**File Not Found:**
```python
# Verify file exists
try:
    metadata = mcp__gdrive__drive_files_metadata(file_id="abc123")
except:
    # Handle missing file
    pass
```

**Permission Denied:**
```bash
# Re-authenticate with proper scopes
gcloud auth login --enable-gdrive-access
```

## Quick Reference

### MCP Tools by Category

**Authentication:**
- `drive_check_auth`, `gmail_check_auth`, `calendar_check_auth`

**Drive Files:**
- `drive_files_list`, `drive_files_download`, `drive_files_upload`
- `drive_files_copy`, `drive_files_rename`, `drive_files_delete`
- `drive_files_metadata`, `drive_files_validate_markdown`, `drive_files_list_tabs`

**Drive Folders:**
- `drive_folders_create`, `drive_folders_move`

**Permissions:**
- `permissions_grant`, `permissions_list`, `permissions_update`, `permissions_revoke`

**Docs:**
- `docs_create`, `docs_download`, `docs_apply_text_diff`, `docs_find_replace`

**Docs Comments:**
- `docs_comments_list`, `docs_comments_get`, `docs_comments_create`
- `docs_comments_reply`, `docs_comments_resolve`

**Sheets:**
- `sheets_create`, `sheets_update`, `sheets_append`

**Calendar:**
- `calendar_list`, `calendar_search`, `calendar_create`
- `calendar_update`, `calendar_delete`, `calendar_update_reminders`

**Gmail:**
- `gmail_search`, `gmail_get`, `gmail_thread`
- `gmail_send`, `gmail_draft`, `gmail_send_draft`
- `gmail_list_labels`, `gmail_label`, `gmail_archive`, `gmail_star`
- `gmail_trash`, `gmail_delete`, `gmail_download_attachment`

**Tasks:**
- `tasks_list_lists`, `tasks_get_list`, `tasks_list`, `tasks_get`
- `tasks_create_list`, `tasks_create`, `tasks_update`
- `tasks_complete`, `tasks_delete`, `tasks_clear_completed`

**XLSX:**
- `parse_xlsx`, `write_xlsx`

## Summary

**Total MCP Tools:** 40+ comprehensive Google Workspace operations

**Use MCP tools for:**
- All CRUD operations (Create, Read, Update, Delete)
- Searching and filtering content
- Managing permissions and access control
- Email, calendar, and task management
- Document editing and collaboration
- Spreadsheet data manipulation

**Use CLI for:**
- Interactive authentication flows
- Shell script automation
- Batch operations with pipes
- Human-readable output formatting
- Quick shortcuts (calendar today/tomorrow)

**Key advantages:**
- **MCP**: Structured responses, programmatic access, direct integration
- **CLI**: Scriptable, interactive, human-friendly, shell integration