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

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

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

MCP-Specific Best Practices

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

CLI-Specific Best Practices

JSON output for scripting: Use
```
--json
```
flag with
```
jq
```
for processing
Confirm destructive operations: CLI prompts for confirmations by default
Use environment variables: Set
```
GOOGLE_CLOUD_PROJECT
```
for quota management
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

gspace

NPX Install

Tags

SKILL.md Content

Google Workspace (gspace) Skill

MCP vs CLI: When to Use Each

Use MCP Tools When:

Use CLI When:

Working with Google Docs/Sheets/Slides URLs

CLI Commands for Downloading

URL Patterns and File ID Extraction

Common URL Operations

Workflow: Fetch and Download from URL

Supported Export Formats

URL-Based Workflows

MCP Tools Complete Reference

Authentication Tools

mcp__gdrive__drive_check_auth

mcp__gdrive__gmail_check_auth

mcp__gdrive__calendar_check_auth

Google Drive File Operations

mcp__gdrive__drive_files_list

mcp__gdrive__drive_files_download

mcp__gdrive__drive_files_upload

mcp__gdrive__drive_files_copy

mcp__gdrive__drive_files_rename

mcp__gdrive__drive_files_delete

mcp__gdrive__drive_files_metadata

mcp__gdrive__drive_files_validate_markdown

mcp__gdrive__drive_files_list_tabs

Google Drive Folder Operations

mcp__gdrive__drive_folders_create

mcp__gdrive__drive_folders_move

Permissions Management

mcp__gdrive__permissions_grant

mcp__gdrive__permissions_list

mcp__gdrive__permissions_update

mcp__gdrive__permissions_revoke

Google Docs Operations

mcp__gdrive__docs_create

mcp__gdrive__docs_download

mcp__gdrive__docs_apply_text_diff

mcp__gdrive__docs_find_replace

Google Docs Comments

mcp__gdrive__docs_comments_list

mcp__gdrive__docs_comments_get

mcp__gdrive__docs_comments_create

mcp__gdrive__docs_comments_reply

mcp__gdrive__docs_comments_resolve

Google Sheets Operations

mcp__gdrive__sheets_create

mcp__gdrive__sheets_update

mcp__gdrive__sheets_append

Google Calendar Operations

mcp__gdrive__calendar_list

mcp__gdrive__calendar_search

mcp__gdrive__calendar_create

mcp__gdrive__calendar_update

mcp__gdrive__calendar_delete

mcp__gdrive__calendar_update_reminders

Gmail Operations

mcp__gdrive__gmail_search

mcp__gdrive__gmail_get

mcp__gdrive__gmail_thread

mcp__gdrive__gmail_send

mcp__gdrive__gmail_draft

mcp__gdrive__gmail_send_draft

mcp__gdrive__gmail_list_labels

mcp__gdrive__gmail_label

mcp__gdrive__gmail_archive

mcp__gdrive__gmail_star

mcp__gdrive__gmail_trash

mcp__gdrive__gmail_delete

mcp__gdrive__gmail_download_attachment

Google Tasks Operations

mcp__gdrive__tasks_list_lists

mcp__gdrive__tasks_get_list

mcp__gdrive__tasks_list

mcp__gdrive__tasks_get

mcp__gdrive__tasks_create_list

`mcpgdrivedrive_check_auth`

`mcpgdrivegmail_check_auth`

`mcpgdrivecalendar_check_auth`

`mcpgdrivedrive_files_list`

`mcpgdrivedrive_files_download`

`mcpgdrivedrive_files_upload`

`mcpgdrivedrive_files_copy`

`mcpgdrivedrive_files_rename`

`mcpgdrivedrive_files_delete`

`mcpgdrivedrive_files_metadata`

`mcpgdrivedrive_files_validate_markdown`

`mcpgdrivedrive_files_list_tabs`

`mcpgdrivedrive_folders_create`

`mcpgdrivedrive_folders_move`

`mcpgdrivepermissions_grant`

`mcpgdrivepermissions_list`

`mcpgdrivepermissions_update`

`mcpgdrivepermissions_revoke`

`mcpgdrivedocs_create`

`mcpgdrivedocs_download`

`mcpgdrivedocs_apply_text_diff`

`mcpgdrivedocs_find_replace`

`mcpgdrivedocs_comments_list`

`mcpgdrivedocs_comments_get`

`mcpgdrivedocs_comments_create`

`mcpgdrivedocs_comments_reply`

`mcpgdrivedocs_comments_resolve`

`mcpgdrivesheets_create`

`mcpgdrivesheets_update`

`mcpgdrivesheets_append`

`mcpgdrivecalendar_list`

`mcpgdrivecalendar_search`

`mcpgdrivecalendar_create`

`mcpgdrivecalendar_update`

`mcpgdrivecalendar_delete`

`mcpgdrivecalendar_update_reminders`

`mcpgdrivegmail_search`

`mcpgdrivegmail_get`

`mcpgdrivegmail_thread`

`mcpgdrivegmail_send`

`mcpgdrivegmail_draft`

`mcpgdrivegmail_send_draft`

`mcpgdrivegmail_list_labels`

`mcpgdrivegmail_label`

`mcpgdrivegmail_archive`

`mcpgdrivegmail_star`

`mcpgdrivegmail_trash`

`mcpgdrivegmail_delete`

`mcpgdrivegmail_download_attachment`

`mcpgdrivetasks_list_lists`

`mcpgdrivetasks_get_list`

`mcpgdrivetasks_list`

`mcpgdrivetasks_get`

`mcpgdrivetasks_create_list`

`mcpgdrivetasks_create`

`mcpgdrivetasks_update`

`mcpgdrivetasks_complete`

`mcpgdrivetasks_delete`

`mcpgdrivetasks_clear_completed`

`mcpgdriveparse_xlsx`

`mcpgdrivewrite_xlsx`