Google Workspace MCP Server (google-workspace-mcp)

A secure, client-agnostic Model Context Protocol (MCP) server that provides AI agents (Claude, Cursor, ChatGPT, Gemini, Antigravity) with controlled, user-authorized actions in Google Workspace.

Capabilities (Version 1)

1. gmail_send_email: Sends plain-text emails through the user's authorized Gmail account. Supports to, cc, bcc, subject, and body. Includes a configurable safe confirmation policy.

2. google_docs_append_text: Non-destructively appends plain text to the very end of an existing Google Doc. Guaranteed never to overwrite, delete, or replace existing document content.

Related MCP server: Google Workspace MCP Server

Architectural Highlights

• Client Agnostic: 100% compliant with standard MCP JSON-RPC 2.0 specifications. No client-specific or vendor-specific dependencies in business logic.

• Least-Privilege Scopes: Requests only https://www.googleapis.com/auth/gmail.send and https://www.googleapis.com/auth/documents. Broad read scopes (e.g. gmail.readonly, full drive) are strictly prohibited.

• Safe Confirmation Policy: By default (REQUIRE_EMAIL_CONFIRMATION=true), the server forces a two-phase commit on outbound emails, requiring the calling agent to confirm intent with the user before dispatching.

• Strict Privacy & Zero PII Logging: All logs output to stderr in structured JSON. Email bodies, document content, recipient addresses, and OAuth tokens are strictly masked and redacted.

• Stdio Integrity: The stdout stream is exclusively reserved for framed MCP protocol communication.

For complete architectural details, see Docs/Architecture.md.

Prerequisites

• Node.js: v20.0.0 or higher

• Google Cloud Account: With permission to create an OAuth 2.0 application

Quickstart & Setup Guide

1. Google Cloud Platform Configuration

1. Visit the Google Cloud Console.

2. Create a new Google Cloud Project (e.g. google-workspace-mcp-app).

3. Enable Required APIs:

   • Navigate to APIs & Services > Library.

   • Search for Gmail API and click Enable.

   • Search for Google Docs API and click Enable.

4. Configure OAuth Consent Screen:

   • Navigate to APIs & Services > OAuth consent screen.

   • Choose External (or Internal if using a Google Workspace organization).

   • Fill in the required application name and support email.

   • On the Scopes step, add the following two scopes:

     • https://www.googleapis.com/auth/gmail.send

     • https://www.googleapis.com/auth/documents

   • Under Test users, add your Google email address.

5. Create OAuth Credentials:

   • Navigate to APIs & Services > Credentials.

   • Click Create Credentials > OAuth client ID.

   • Application type: Web application.

   • Name: Workspace MCP Client.

   • Authorized redirect URIs: http://localhost:3000/oauth2callback.

   • Click Create and copy your Client ID and Client Secret.

2. Configure Environment

Copy the example environment template and configure your credentials:

cp .env.example .env

Edit .env:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback
TOKEN_STORAGE_PATH=./.credentials/tokens.json
REQUIRE_EMAIL_CONFIRMATION=true
LOG_LEVEL=info

3. Authorize Your Google Account

Run the interactive authorization CLI:

npm run auth

• Your default browser will open automatically to Google's OAuth consent screen.

• Select your test Google account and grant the requested Gmail and Google Docs permissions.

• Once completed, the tokens will be automatically saved to ./.credentials/tokens.json with secure 0600 permissions.

4. Build the Project

npm run build

Client Configuration Examples

Claude Desktop

Add the following to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["c:/Users/jaya.manocha/Documents/myProjects/MCP/dist/src/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "TOKEN_STORAGE_PATH": "c:/Users/jaya.manocha/Documents/myProjects/MCP/.credentials/tokens.json",
        "REQUIRE_EMAIL_CONFIRMATION": "true"
      }
    }
  }
}

Cursor IDE

Create or update .cursor/mcp.json in your project root or user config:

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["c:/Users/jaya.manocha/Documents/myProjects/MCP/dist/src/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "TOKEN_STORAGE_PATH": "c:/Users/jaya.manocha/Documents/myProjects/MCP/.credentials/tokens.json"
      }
    }
  }
}

Tool Reference

gmail_send_email

Sends an email using the authenticated Gmail account.

Parameters:

• to (array of strings, required): One or more valid recipient email addresses.

• subject (string, required): Non-empty subject line (max 500 characters).

• body (string, required): Plain-text body content.

• cc (array of strings, optional): Carbon-copy recipient email addresses.

• bcc (array of strings, optional): Blind-carbon-copy recipient email addresses.

• confirm_send (boolean, optional): Explicit confirmation flag. Required when REQUIRE_EMAIL_CONFIRMATION=true.

• request_id (string, optional): Correlation ID for traceability and duplicate prevention.

Example Response:

{
  "success": true,
  "message_id": "18f0a1b2c3d4e5f6",
  "thread_id": "18f0a1b2c3d4e5f6",
  "status": "Email sent"
}

google_docs_append_text

Appends text to the end of a document without modifying prior contents.

Parameters:

• document_id (string, required): Google Docs document ID or full docs.google.com URL.

• text (string, required): Exact plain text to append.

• prepend_newline (boolean, optional, default: true): Inserts a newline separator before the appended text.

• request_id (string, optional): Correlation ID.

Example Response:

{
  "success": true,
  "document_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
  "status": "Text appended to Google Doc",
  "characters_appended": 42
}

Error Handling & Taxonomy

When a failure occurs, tools return a standardized error object:

{
  "success": false,
  "error_code": "RESOURCE_NOT_FOUND",
  "message": "The requested Google Doc or mailbox resource was not found. Please verify the document ID.",
  "retryable": false
}

Testing

Run the automated test suite with Vitest:

npm test

Build verification:

npm run build

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.