Google Workspace MCP Server

A Model Context Protocol (MCP) server that provides 171 tools for interacting with Google Workspace APIs: Gmail, Calendar, Drive, Docs, Sheets, Slides, People (Contacts), Tasks, Forms, Meet, and Admin Directory. Built with TypeScript, the official googleapis client library, and the MCP SDK high-level API.

Install from npm:

npm install google-workspace-mcp-dg
# or run without installing:
npx google-workspace-mcp-dg            # starts the MCP server (stdio)
npx google-workspace-mcp-dg auth       # interactive OAuth setup CLI

Features

• Gmail: List, search, send (with attachments), create drafts, reply (with proper threading), get attachments, modify labels, watch for changes
• Calendar: List/create/update/delete events, respond to invitations (correct self attendee patching), find free time, quick add with natural language, ACL management
• Drive: List/search files, create/update/delete/copy, upload/download (with size guard), export Google formats, manage permissions, shared drives, revisions, incremental sync
• Docs: Create, read, insert/replace text, apply styles, batch updates, tables, images, page breaks
• Sheets: Create, read/write ranges, batch updates, append, formatting (with real sheet-name → sheetId resolution), add/delete sheets, charts, data validation, named ranges
• Slides: Create presentations, add slides, insert text/images, format text, duplicate/delete, thumbnails, tables, replace all text
• People/Contacts: List/search/create/update/delete contacts, directory search, contact groups, other contacts
• Tasks: Task lists and tasks CRUD, subtasks, move, clear completed
• Forms: Create forms, add questions (all common types), read responses, quizzes, Pub/Sub watches
• Meet: Create meeting spaces, conference records, participants, recordings, transcripts, end active conference
• Admin Directory: Users, groups, org units, aliases — full Workspace admin automation
• Multi-workspace: Multiple Google accounts with per-workspace credentials, tokens, sender names and signatures
• Automatic OAuth: Local callback server captures the authorization code — no manual copy/paste
• Robust MIME builder: multipart/mixed attachments, base64 UTF-8 bodies (no accent corruption), RFC 2047 headers, header-injection protection
• Meta-Mode: Progressive tool discovery via 4 meta-tools instead of 171 individual tools (99% token reduction)

Quick Start

1. Google Cloud setup

1. Go to Google Cloud Console and create or select a project.
2. Enable the APIs: Gmail, Calendar, Drive, Docs, Sheets, Slides, People, Admin SDK.
3. Create an OAuth 2.0 Client ID (Desktop app type) under APIs & Services → Credentials.
4. Add the required scopes to your OAuth consent screen (see .docs/authentication.md).

2. Install and configure

Option A — install from npm (recommended):

npm install -g google-workspace-mcp-dg

# Configure credentials as environment variables (no .env file needed),
# then run the interactive auth CLI:
google-workspace-mcp auth

Option B — from source (this repository):

git clone https://github.com/diegoalgg88/google-workspace-mcp.git
cd google-workspace-mcp
npm install
npm run build

# Create .env with your credentials (see .env.example or below)
# Then run the interactive auth CLI:
npm run auth

The auth CLI opens your browser automatically and captures the OAuth callback on localhost:7777 — no manual code pasting required. When installed from npm, credentials come from the process environment (MCP client env block, shell, or CI); when running from source, npm start/npm run auth load .env automatically via Node's --env-file.

3. Configure your MCP client

Qwen Code (~/.qwen/settings.json) or Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "google-workspace-mcp-dg"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GOOGLE_REDIRECT_URI": "http://localhost:7777/oauth/callback",
        "GOOGLE_WORKSPACE_SERVICES": "gmail,calendar,drive,docs,sheets,slides,people,admin,tasks,forms,meet",
        "GOOGLE_WORKSPACE_META_MODE": "false"
      }
    }
  }
}

Or, if you cloned the repository, point command/args at the local build:

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["C:\\path\\to\\google-workspace-mcp\\dist\\server.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GOOGLE_REDIRECT_URI": "http://localhost:7777/oauth/callback",
        "GOOGLE_WORKSPACE_SERVICES": "gmail,calendar,drive,docs,sheets,slides,people"
      }
    }
  }
}

See example-config.json for a template.

Authentication

Two ways to provide OAuth credentials:

| Method | How | |--------|-----| | Environment variables (recommended) | GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET in .env (loaded automatically by npm run auth / npm start via Node's --env-file) | | Credentials file | npm run auth -- --credentials path/to/credentials.json |

Tokens are stored per-workspace in ~/.config/google-workspace-mcp/ with 0600 permissions, and refreshed automatically before every API call.

Note: if you add new scopes later, re-run npm run auth → auth to re-authorize.

How authentication works when installed from npm

The OAuth flow is owned by this server (Google OAuth via its auth CLI), not by the MCP client. This is a stdio server, so the MCP client's built-in OAuth/dynamic-registration flow (Cannot perform dynamic registration without authorization URL) does not apply and will always fail — ignore it.

When installed from npm there is no .env file, so the one-time authorization is:

# Option 1: credentials in the shell environment
GOOGLE_CLIENT_ID=... GOOGLE_CLIENT_SECRET=... npx -y -p google-workspace-mcp-dg google-workspace-mcp auth

# Option 2: credentials file from Google Cloud Console (cleanest)
npx -y -p google-workspace-mcp-dg google-workspace-mcp auth --credentials /path/to/credentials.json

Key points:

• The token store (~/.config/google-workspace-mcp/) is shared — a token authorized from a source checkout works with the npm install and vice versa, as long as the same GOOGLE_CLIENT_ID is used (it binds the refresh token).
• The running MCP server hot-reloads tokens from disk on the next tool call; re-authorizing with the auth CLI is picked up without a restart. If tools fail with invalid_grant, the agent can also call auth_reauthenticate to start a browser re-authorization in-session and poll auth_reauthenticate_status until it completes.
• The auth CLI starts a temporary callback server on localhost:7777 and opens your browser — identical flow whether installed from npm or source.

Available Tools (171)

Summary by service — full reference in .docs/services.md:

| Service | Tools | Examples | |---------|------:|----------| | Accounts | 7 | list_workspaces, create_workspace, update_workspace, delete_workspace, get_workspace, auth_reauthenticate, auth_reauthenticate_status | | Admin Directory | 23 | admin_list_users, admin_create_user, admin_list_groups, admin_create_org_unit | | Gmail | 22 | gmail_send_email (attachments ✓), gmail_get_thread, gmail_batch_modify, gmail_watch | | Calendar | 17 | calendar_create_event, calendar_respond_to_event, calendar_list_recurring_instances, calendar_add_acl_rule | | Drive | 19 | drive_upload_file (streaming), drive_list_changes, drive_get_revisions, drive_list_shared_drives | | Docs | 11 | docs_create_document, docs_insert_table, docs_insert_image, docs_apply_style | | Sheets | 15 | sheets_update_range, sheets_add_chart, sheets_set_data_validation, sheets_create_named_range | | Slides | 13 | slides_create_slide, slides_create_table, slides_replace_all_text, slides_insert_image | | People | 13 | people_search_contacts, people_create_contact, people_list_other_contacts | | Tasks | 10 | tasks_list_tasks, tasks_create_task, tasks_move_task, tasks_clear_completed | | Forms | 9 | forms_create_form, forms_add_question, forms_list_responses, forms_create_watch | | Meet | 11 | meet_create_space, meet_list_conferences, meet_get_transcript_entries, meet_end_active_conference |

Configuration

| Variable | Description | Default | |----------|-------------|---------| | GOOGLE_CLIENT_ID | OAuth Client ID | Required | | GOOGLE_CLIENT_SECRET | OAuth Client Secret | Required | | GOOGLE_REDIRECT_URI | OAuth redirect URI | http://localhost:7777/oauth/callback | | GOOGLE_WORKSPACE_SERVICES | Comma-separated services to enable (filters registered tools) | All | | GOOGLE_WORKSPACE_META_MODE | Enable Meta-Mode: expose 4 meta-tools instead of 171 individual tools for progressive discovery | false |

Meta-Mode (Progressive Tool Discovery)

When GOOGLE_WORKSPACE_META_MODE=true, the server registers only 4 meta-tools instead of all 171 individual tools. This dramatically reduces token usage in the model's context window (from ~171 tool schemas to just 4).

Meta-Tools

| Tool | Purpose | |------|---------| | list_domains | List all available domains (services): admin, gmail, calendar, drive, docs, sheets, slides, people, tasks, forms, meet, auth | | list_domain_tools | List all tools in a specific domain with one-line descriptions | | get_tool_schema | Get the full JSON schema (input parameters) for a specific tool | | execute_tool | Execute a tool by name with arguments |

Usage Flow

1. list_domains                    → see all available services
2. list_domain_tools "gmail"       → see Gmail's 22 tools with descriptions
3. get_tool_schema "gmail_send_email" → get full JSON schema for send email
4. execute_tool "gmail_send_email" { to: ["[email protected]"], subject: "Hi", body: "..." }

Benefits

• 99% token reduction in initial context (4 meta-tools vs 171 schemas)
• On-demand loading — only the schema you need is fetched
• Respects GOOGLE_WORKSPACE_SERVICES — filtered domains/tools still apply
• Same handlers — no logic changes; meta-tools delegate to existing implementations

When to Use

| Scenario | Recommendation | |----------|----------------| | Default (small context window, few services) | Normal mode (all tools visible) | | All 10 services enabled, context pressure | Meta-Mode enabled | | Agent with many MCP servers connected | Meta-Mode + filtered services | | Debugging / human inspection of available tools | Normal mode |

Note: Meta-Mode adds 2-3 extra LLM turns per actual tool call (discovery → schema → execute). Enable when the token savings outweigh the turn cost.

Development

npm install        # install dependencies
npm run build      # compile to dist/
npm run dev        # watch mode (loads .env)
npm run auth       # auth CLI (loads .env)
npm test           # vitest suite (64 tests)

Project Structure

google-workspace-mcp/
├── src/
│   ├── server.ts              # MCP server entry (stdio transport, service filter)
│   ├── index.ts               # Public library exports
│   ├── types.ts               # Shared type definitions
│   ├── auth/
│   │   ├── google-auth.ts     # OAuth2 service: tokens, workspaces, refresh
│   │   └── auth-cli.ts        # Interactive CLI with automatic OAuth callback
│   └── services/
│       ├── accounts.ts        # Workspace/account tools
│       ├── admin.ts           # Admin Directory tools
│       ├── gmail.ts           # Gmail tools
│       ├── calendar.ts        # Calendar tools
│       ├── drive.ts           # Drive tools
│       ├── docs.ts            # Docs tools
│       ├── sheets.ts          # Sheets tools (+ A1 range parsing)
│       ├── slides.ts          # Slides tools
│       ├── people.ts          # People/Contacts tools
│       ├── tasks.ts           # Tasks tools
│       ├── forms.ts           # Forms tools
│       ├── meet.ts            # Meet tools
│       ├── mime.ts            # RFC 822/MIME message builder
│       ├── mcp-helpers.ts     # MCP result helpers, hex color parser
│       ├── tool-registry.ts   # Tool registry for Meta-Mode
│       └── meta-tools.ts      # 4 meta-tools for progressive discovery
├── test/                      # vitest suite (mime, helpers, auth, tool-registry, meta-mode)
├── .docs/                     # Technical documentation
├── example-config.json        # MCP client config template
└── USER_TUTORIAL.md           # Step-by-step user guide

Documentation

• .docs/architecture.md — system design and data flow
• .docs/authentication.md — OAuth setup, scopes, token lifecycle
• .docs/services.md — full tool reference with parameters
• .docs/development.md — building, testing, contributing
• .docs/meta-mode.md — Meta-Mode deep dive
• USER_TUTORIAL.md — end-user walkthrough

License

MIT — see LICENSE. Published on npm as google-workspace-mcp-dg.