Gspace

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

# 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

# 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

# Add comment to document
mcp__gdrive__docs_comments_create(
    file_id="ABC123",
    content="This section needs updating"
)

Workflow 3: Share Doc from URL

# 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

# 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.

# 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.

mcp__gdrive__gmail_check_auth()

mcp__gdrive__calendar_check_auth

Verify Calendar API authentication and required scopes.

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)

# 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

# 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)

# 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

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

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)

# 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

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

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

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

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)

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"

# 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

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)

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

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

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)

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)

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

# 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

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

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

# 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"

# 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

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

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)

# 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"

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)

# 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)

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

# 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

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

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"

# 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

# 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

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

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

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

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

mcp__gdrive__gmail_send_draft(draft_id="draft123")

mcp__gdrive__gmail_list_labels

List all Gmail labels.

# 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

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

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)

# 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

mcp__gdrive__gmail_trash(message_id="msg123")

mcp__gdrive__gmail_delete

Permanently delete messages.

Parameters:

• message_id (string, required): Message ID

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

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.

# 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

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

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

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

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

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"

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

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

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

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

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

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

# Check authentication status
gspace auth check

# Login (interactive)
gspace auth login

Drive File Operations

# 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

# Create folder
gspace drive folders create "Project Documents"

# Move file to folder
gspace drive folders move FILE_ID FOLDER_ID

Permissions

# 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

# 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

# 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

# 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

# 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

# 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)

# 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)

# 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)

# 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)

# 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)

# 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:

# Check auth status
mcp__gdrive__drive_check_auth()

File Not Found:

# Verify file exists
try:
    metadata = mcp__gdrive__drive_files_metadata(file_id="abc123")
except:
    # Handle missing file
    pass

Permission Denied:

# 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,

…(truncated)