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

Go to https://console.cloud.google.com and create a new project (or select an existing one)
Navigate to APIs & Services > Library
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

Go to APIs & Services > Credentials
Click Create Credentials > OAuth client ID
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
Back in Credentials, create an OAuth client ID:
- Application type: Desktop app
- Name: anything (e.g. "GSuite MCP Server")
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

MCP Servers