Noureddine RAMDI / Integrating Google Workspace with AI agents via the google-docs-mcp server

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
1128 Words
github-stars typescript google-workspace mcp oauth2 ai-agents automation

a-bonus/google-docs-mcp

The google-docs-mcp project offers something few tools do: it lets AI agents like Claude Desktop, Cursor, and Windsurf directly interact with your full Google Workspace suite — Docs, Sheets, Drive, Gmail, and Calendar — as callable endpoints. This is more than just basic read or write access; the server supports complex operations like markdown-to-doc conversion, sheet formatting, email searching, and calendar event management. It effectively transforms AI assistants from passive chat partners into active coworkers that can manipulate your documents, spreadsheets, emails, and calendar events programmatically.

exposing google workspace to ai agents through an mcp server

Under the hood, google-docs-mcp is a TypeScript-based Model Context Protocol (MCP) server. MCP is a protocol designed to let AI agents call external tools securely and interactively. This server wraps the entire Google Workspace API surface — including Google Docs API, Sheets API, Drive API, Gmail API, and Calendar API — into MCP tools that AI agents can invoke.

The architecture supports two deployment modes. First, local execution via npx where OAuth tokens are stored on the local filesystem (~/.config/google-docs-mcp/token.json). This mode is convenient for single users experimenting or running AI agents on their own machines.

Second, it can be deployed remotely on Google Cloud Run with Firestore-backed token storage and OAuth 2.1 support tailored for team environments. This enables seamless multi-user setups without each user handling tokens manually.

The server surface is deep: it goes beyond CRUD operations to handle nuanced document and sheet features. For example, it supports markdown-to-Google Docs conversion, cell and conditional formatting in Sheets, row grouping, dropdown validations, sheet protection, image insertions, threaded comments, Gmail search and sending, and calendar event CRUD. This breadth makes it valuable for complex workflows and agentic automation.

Technically, the stack is TypeScript running on Node.js, integrating tightly with Google’s official APIs. The OAuth client credentials and refresh tokens are securely managed, with verbose logging that supports debugging during development or production use.

technical strengths and design tradeoffs behind google-docs-mcp

What distinguishes this repo is the comprehensiveness of its Google Workspace API coverage presented as a single MCP server. Most tools expose only one or two Google services or provide partial API coverage. Here, the integration handles five major Google services with advanced features.

This depth requires careful token and permission management. The server supports storing tokens locally for single users and Firestore for multi-user cloud deployments, reflecting a tradeoff between simplicity and scalability.

The codebase emphasizes developer experience (DX) with one-click npx authorization flow for local use, reducing friction in getting started. The OAuth consent screen setup, while standard for Google Cloud projects, is documented clearly but still requires manual steps that might intimidate newcomers.

Under the hood, the tool translates Google’s often complex API calls and data formats into MCP tool calls that AI agents understand. This abstraction layer is surprisingly clean, making it easier for AI clients to leverage the full power of Google Workspace without dealing with raw REST or gRPC APIs.

The server supports multiple MCP clients like Claude Desktop, Cursor, and Windsurf, showing attention to interoperability. It also balances synchronous local command execution with streamable HTTP transport in cloud deployments, providing flexibility in integration patterns.

Tradeoffs include the complexity of maintaining OAuth tokens securely, especially when deploying remotely. Firestore-backed token storage requires additional cloud infrastructure and configuration, potentially increasing the operational footprint.

Also, while the API coverage is rich, it relies on the underlying Google API limits and quotas, which could become bottlenecks in high-throughput environments.

quick start with google-docs-mcp

Getting started requires setting up a Google Cloud OAuth Client and authorizing the MCP server to access your Google Workspace data. The project README provides a clear 3-step process:

  1. Create a Google Cloud OAuth Client:

    • Enable the Docs, Sheets, Drive, Gmail, and Calendar APIs in the Google Cloud Console.
    • Configure the OAuth consent screen (External, add your email as a test user).
    • Create an OAuth client ID (Desktop app type).
    • Copy the client ID and client secret.

  2. Authorize locally using npx:

GOOGLE_CLIENT_ID="your-client-id" \
GOOGLE_CLIENT_SECRET="your-client-secret" \
npx -y @a-bonus/google-docs-mcp auth

This command opens your browser to complete Google authorization. After approval, your refresh token is saved locally.

  1. Add the MCP server configuration to your AI client (e.g., Claude Desktop, Cursor, Windsurf):
{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a-bonus/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

The server starts automatically when your MCP client needs it.

For remote deployment on Cloud Run, the project supports deploying the server once for a team with Firestore token storage and MCP OAuth 2.1, enabling users to authenticate seamlessly via the client.

gcloud run deploy google-docs-mcp \
  --source . \
  --region europe-west3 \
  --port 8080 \
  --allow-unauthenticated \
  --set-env-vars "^|^MCP_TRANSPORT=httpStream|BASE_URL=https://your-service.run.app|GOOGLE_CLIENT_ID=...|GOOGLE_CLIENT_SECRET=...|TOKEN_STORE=firestore|JWT_SIGNING_KEY=your-secret-key"

Users then add the remote URL to their MCP client configuration, eliminating local token management.

verdict

google-docs-mcp is a practical and well-crafted bridge between AI agents and Google Workspace productivity tools. Its comprehensive API coverage and support for advanced document and email operations make it valuable for developers building autonomous AI workflows that need real interaction with Docs, Sheets, Gmail, and Calendar.

The project is especially relevant for practitioners using MCP-compatible AI agents like Claude Desktop who want to add real-world document collaboration and email management capabilities.

The main limitations lie in the OAuth setup complexity, which requires manual steps and Google Cloud Console familiarity, and the operational overhead when deploying remotely with Firestore token storage.

For solo developers or small teams comfortable with OAuth, the local npx flow is straightforward and well-documented. For larger teams, the Cloud Run deployment offers scalability but demands cloud infrastructure management.

Overall, google-docs-mcp solves a real problem by enabling AI agents to move beyond static responses to active document and email coworkers, a significant step toward practical AI agent integration in productivity environments.

→ GitHub Repo: a-bonus/google-docs-mcp ⭐ 541 · TypeScript