gws-mcp (Google Workspace MCP Server)

A Model Context Protocol (MCP) server providing safe, auditable, and comprehensive control over Google Drive, Google Sheets, Google Docs, and Google Slides.

Built for AI agents and scheduled pipelines to create, read, edit, format, and organize Google Workspace resources with safety-first guardrails (dry_run previews and append-only audit logs).

🌟 Key Features

• Safe-by-Default Execution: Every mutating tool implements a two-phase plan() $\to$ execute() pipeline with dry-run support. Passing dry_run: true computes the exact diff without modifying resources.

• Append-Only Audit Logging: All mutations record intent and outcome entries to a local JSONL audit trail without logging customer data or PII.

• Dual Authentication Modes:

  • Service Account (AUTH_MODE=service_account): Ideal for backend automations, CRMs, and scheduled workers operating on shared files.

  • User OAuth 2.0 (AUTH_MODE=oauth): For interactive user sessions with support for creating new files in personal Google Drives.

• Rich Formatting Engine: Pixel-level styling, typography, RGB colors, alignments, wrap rules, bullet lists, dimension management, tables, and images.

Related MCP server: mcp-gsheet

🧰 Complete Tool Catalog (24 Tools)

📊 Google Sheets (9 Tools)

1. sheets_read_range — Read cell values using standard A1 notation (e.g. "Leads!A1:F50").

2. sheets_append_rows — Append rows with deduplication keys (dedupKey) and formula injection defense.

3. sheets_update_range — Overwrite cell values or write to new columns with before/after diffs in dry-run mode.

4. sheets_format — Format cells: bold, italic, strikethrough, underline, font size, font family, text RGB, background RGB, number formats, horizontal/vertical alignment (TOP/MIDDLE/BOTTOM), text wrapping (WRAP/CLIP/OVERFLOW), column widths, row heights, and freeze panes.

5. sheets_manage_dimensions — Structural operations: insert blank rows/columns anywhere, delete row/column ranges, or append dimensions to expand sheet boundaries.

6. sheets_clear — Clear VALUES, FORMAT, or ALL across a range without deleting grid rows.

7. sheets_add_tab — Create new tabs with optional header row initialization.

8. sheets_duplicate_tab — Clone an existing tab (preserving formulas, styles, and data) into a new tab.

9. sheets_delete_tab — Delete a tab by name (with safeguards against deleting the last remaining tab).

📄 Google Docs (8 Tools)

1. docs_read — Read complete plain text content from documents, tables, and outlines.

2. docs_style — Format text and paragraphs: headings (HEADING_1 to HEADING_6, TITLE, SUBTITLE), bold, italic, underline, strikethrough, font size, font family, foreground RGB, background highlight RGB, hyperlinks (link), paragraph alignment, line spacing, and paragraph margins (spaceAbove, spaceBelow).

3. docs_insert_text — Insert text at specific character indices or append to body/headers/footers.

4. docs_replace_text — Search and replace template placeholders (e.g. {{client_name}}) case-sensitively or insensitively.

5. docs_insert_table — Insert $R \times C$ tables at any character position or append to the end.

6. docs_insert_image — Insert inline or floating/positioned images with custom dimensions, offsets, and text wrap modes (WRAP_TEXT, IN_FRONT_OF_TEXT, BEHIND_TEXT, etc.).

7. docs_insert_bullets — Convert paragraphs into bulleted lists (BULLET_DISC_CIRCLE_SQUARE, BULLET_CHECKBOX, NUMBERED_DECIMAL_ALPHA_ROMAN, etc.) or remove bullets.

8. docs_delete_content — Remove character ranges or sections from document body, headers, or footers.

📽️ Google Slides (6 Tools)

1. slides_read — Read presentation structure, slide IDs, elements, and extracted text.

2. slides_create — Create a new blank presentation or copy from a template deck.

3. slides_add_slide — Insert a new slide with predefined layouts (TITLE_AND_BODY, SECTION_HEADER, MAIN_POINT, BLANK, etc.).

4. slides_duplicate_slide — Duplicate a designed slide layout to populate repeated items (e.g. case studies, portfolios).

5. slides_replace_text — Find and replace {{placeholders}} across the entire deck.

6. slides_insert_image — Insert images onto slides at specific $(X, Y)$ positions and sizes.

🔍 Google Drive (5 Tools)

1. drive_find — Search files and folders by name and MIME type with pagination and truncation awareness.

2. drive_create — Create a new Google Doc, Google Sheet, Google Slides presentation, or Drive folder.

3. drive_copy — Duplicate an existing file or template.

4. drive_share — Share files or folders with user emails (reader, commenter, writer/editor).

5. drive_move — Move files between folders or rename files.

🚀 Setup & Installation

1. Prerequisites

• Node.js 20+

• A Google Cloud Project with the following APIs enabled:

  • Google Drive API

  • Google Sheets API

  • Google Docs API

  • Google Slides API

2. Configure Environment

Copy .env.example to .env:

cp .env.example .env

Option A: Service Account (Recommended for Automations)

1. In Google Cloud Console, create a Service Account and download its JSON key file.

2. Share the target Google Drive folders/files with the service account email.

3. In .env:

   AUTH_MODE=service_account
   GOOGLE_SA_KEY_PATH=./sa-key.json

Option B: User OAuth 2.0 (For Personal User Drives)

1. In Google Cloud Console, create an OAuth 2.0 Client ID (Desktop or Web application).

2. In .env:

   AUTH_MODE=oauth
   GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=your-client-secret
   GOOGLE_REFRESH_TOKEN=your-refresh-token

🔌 Connecting to Claude Desktop / MCP Clients

Add the server to your claude_desktop_config.json or MCP settings:

{
  "mcpServers": {
    "gws": {
      "command": "node",
      "args": ["/absolute/path/to/gws-mcp/dist/server/stdio.js"],
      "env": {
        "AUTH_MODE": "service_account",
        "GOOGLE_SA_KEY_PATH": "/absolute/path/to/sa-key.json",
        "AUDIT_LOG_PATH": "/absolute/path/to/gws-mcp/audit.jsonl"
      }
    }
  }
}

🧪 Development & Testing

# Run unit and contract test suites (100% offline via nock mocks)
npm test

# Check TypeScript types
npm run typecheck

# Build for production
npm run build

# Run integration tests against live Google Cloud APIs (optional)
GWS_INTEGRATION=1 npm run test:integration