GSuite MCP Server

A unified MCP (Model Context Protocol) server for Google Workspace APIs. Consolidates Google Drive, Gmail, Sheets, Docs, and Calendar into a single server with shared OAuth 2.0 authentication — one process, one token, 43 tools.

Features

Google Drive (8 tools)

• List, search, and get files with pagination and filtering
• Download/export files (auto-handles Workspace formats)
• Upload from local disk or create from text content
• Create folders, share files by email, delete (trash or permanent)

Gmail (7 tools)

• List/search messages with Gmail query syntax
• Read full messages with decoded bodies and attachment metadata
• Download attachments to local disk
• Send messages, create drafts, reply with threading
• Supports CC/BCC and file attachments (MIME multipart)

Google Sheets (11 tools)

• List, get, and read spreadsheets with Markdown table output
• Write ranges and append rows with formula support
• Create spreadsheets, add/delete sheets
• Clear ranges and format cells (bold, colors, alignment, number format)

Google Docs (11 tools)

• List, get, and read documents with full text extraction
• Create documents with optional initial content
• Insert text, find and replace, delete content by index range
• Format text (bold, italic, font, colors, links) and paragraphs (headings, alignment, spacing)
• Insert tables and inline images

Google Calendar (6 tools)

• List calendars accessible to the authenticated user
• Create, list, get, update, and delete events
• Supports timed events (ISO8601) and all-day events

Prerequisites

• Python 3.10+
• Google Cloud project with the following APIs enabled:
  • Google Drive API
  • Gmail API
  • Google Sheets API
  • Google Docs API
  • Google Calendar API
• OAuth 2.0 client ID, client secret, and refresh token

Installation

uv sync

Or with pip:

pip install -e .

Configuration

Set three environment variables:

export GSUITE_CLIENT_ID=your-client-id
export GSUITE_CLIENT_SECRET=your-client-secret
export GSUITE_REFRESH_TOKEN=your-refresh-token

Usage with Claude Code

claude mcp add-json gsuite '{
  "command": "uv",
  "args": ["run", "--directory", "/path/to/gsuite-mcp-server", "python", "-m", "gsuite_mcp_server.server"],
  "env": {
    "GSUITE_CLIENT_ID": "your-client-id",
    "GSUITE_CLIENT_SECRET": "your-client-secret",
    "GSUITE_REFRESH_TOKEN": "your-refresh-token"
  }
}'

Available Tools

Google Drive

| Tool | Description | |------|-------------| | gdrive_list_files | List files with pagination, sorting, and folder filtering | | gdrive_search_files | Search by natural language or raw Drive query syntax | | gdrive_get_file | Get file metadata including permissions and sharing status | | gdrive_save_file | Download/export a file to local disk | | gdrive_upload_file | Upload a local file or create from text content | | gdrive_create_folder | Create a new folder | | gdrive_share_file | Share a file with a user by email | | gdrive_delete_file | Move to trash or permanently delete |

Gmail

| Tool | Description | |------|-------------| | gmail_list_messages | List/search messages with Gmail query syntax | | gmail_get_message | Get full message with decoded body and attachment metadata | | gmail_download_attachment | Download an attachment to disk | | gmail_list_labels | List all Gmail labels | | gmail_send_message | Send an email with optional CC/BCC and attachments | | gmail_create_draft | Create a draft email | | gmail_reply_to_message | Reply to a message with threading preserved |

Google Sheets

| Tool | Description | |------|-------------| | gsheets_list_spreadsheets | List spreadsheets with optional name filter | | gsheets_get_spreadsheet | Get spreadsheet metadata and sheet/tab info | | gsheets_read_range | Read a range of cells (A1 notation) | | gsheets_batch_read_ranges | Read multiple ranges in one request | | gsheets_write_range | Write values to a range | | gsheets_append_rows | Append rows after the last data row | | gsheets_create_spreadsheet | Create a new spreadsheet | | gsheets_add_sheet | Add a sheet/tab to a spreadsheet | | gsheets_delete_sheet | Delete a sheet/tab by ID | | gsheets_clear_range | Clear cell values (preserves formatting) | | gsheets_format_cells | Format cells (bold, colors, alignment, number format) |

Google Docs

| Tool | Description | |------|-------------| | gdocs_list_documents | List documents with optional name filter | | gdocs_get_document | Get document metadata (revision, headers, footers, lists) | | gdocs_read_document | Read full text content (paragraphs and tables) | | gdocs_create_document | Create a new document with optional initial text | | gdocs_insert_text | Insert text at a specific index | | gdocs_replace_text | Find and replace text across the entire document | | gdocs_delete_content | Delete content within an index range | | gdocs_format_text | Apply character formatting (bold, italic, font, colors, links) | | gdocs_format_paragraph | Apply paragraph formatting (headings, alignment, spacing) | | gdocs_insert_table | Insert an empty table | | gdocs_insert_image | Insert an inline image from a public URL |

Google Calendar

| Tool | Description | |------|-------------| | gcal_list_calendars | List all accessible calendars | | gcal_create_event | Create a timed or all-day event | | gcal_list_events | List upcoming events with optional search | | gcal_get_event | Get full event details | | gcal_update_event | Update event fields (merge with existing) | | gcal_delete_event | Permanently delete an event |

Setup Guide

Step 1: Create a Google Cloud project

1. Go to https://console.cloud.google.com and create a new project (or select an existing one)
2. Navigate to APIs & Services > Library
3. Enable all five APIs: Google Drive API, Gmail API, Google Sheets API, Google Docs API, Google Calendar API

Step 2: Create OAuth 2.0 credentials

1. Go to APIs & Services > Credentials
2. Click Create Credentials > OAuth client ID
3. If prompted, configure the OAuth consent screen first:
   • Choose External user type (or Internal if using Google Workspace)
   • Fill in the required app name and email fields
   • Add scopes:
     • https://www.googleapis.com/auth/drive
     • https://www.googleapis.com/auth/documents
     • https://www.googleapis.com/auth/spreadsheets
     • https://www.googleapis.com/auth/gmail.readonly
     • https://www.googleapis.com/auth/gmail.send
     • https://www.googleapis.com/auth/gmail.modify
     • https://www.googleapis.com/auth/calendar
   • Add your Google account as a test user
4. Back in Credentials, create an OAuth client ID:
   • Application type: Desktop app
   • Name: anything (e.g. "GSuite MCP Server")
5. Note down the Client ID and Client Secret

Step 3: Obtain a refresh token

uv sync --extra auth
GSUITE_CLIENT_ID=your-client-id GSUITE_CLIENT_SECRET=your-client-secret \
  uv run python -m gsuite_mcp_server.server --auth

This opens a browser for OAuth consent (requesting all scopes at once) and prints the refresh token.

Step 4: Configure and run

Set environment variables and run (see Configuration and Usage with Claude Code above).

License

MIT