MCP Gdocs README

mcp-gdocs

Русский | 中文

Why mcp-gdocs exists

MCP server for Google Docs, Google Drive, and Comments with flexible authentication.

Connect Cursor, Claude Desktop, or any MCP client to your Google Docs and Drive.

Start with a single command: npx -y mcp-gdocs.

Quick Start

1. Google Cloud Setup

1. Go to Google Cloud Console
2. Create or select a project
3. Enable Google Docs API and Google Drive API
4. Choose authentication method (see Authentication below)

2. Add to Cursor / MCP Client

Service Account — share documents with the SA email, then:

{
  "mcpServers": {
    "mcp-gdocs": {
      "command": "npx",
      "args": ["-y", "mcp-gdocs"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

OAuth — run npx -y mcp-gdocs auth first, then:

{
  "mcpServers": {
    "mcp-gdocs": {
      "command": "npx",
      "args": ["-y", "mcp-gdocs"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

The server starts automatically when the MCP client connects.

What Can It Do?

Most write operations accept an items array for bulk execution in a single call. All tools support an optional tabId parameter for multi-tab documents.

Google Docs

Comments

Google Drive

Prompts

Resources

Batch Operations

docs_batch_update combines multiple heterogeneous operations into a single API request (30 request types). Large arrays are automatically split into chunks. Rate limiting uses a shared API semaphore.

Authentication

The server supports multiple authentication methods. If several variables are set, the first found is used: OAuth → SERVICE_ACCOUNT_PATH → CREDENTIALS_CONFIG → GOOGLE_APPLICATION_CREDENTIALS.

Enterprise (Google Workspace): with domain-wide delegation, SA can act on behalf of any domain user via GOOGLE_IMPERSONATE_USER.

Recommendation: use OAuth for personal work in Cursor/Claude Desktop. Use Service Account with impersonation for enterprise automation.

Method A: Service Account

Headless, secure, ideal for server environments.

Steps:

1. GCP Console → IAM & Admin → Service Accounts → Create
2. Download JSON key
3. Share documents/folders with SA email (Editor)

Three ways to provide credentials:

{
  "mcpServers": {
    "mcp-gdocs": {
      "command": "npx",
      "args": ["-y", "mcp-gdocs"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/path/to/service-account-key.json",
        "GOOGLE_IMPERSONATE_USER": "user@yourdomain.com"
      }
    }
  }
}

base64 -w 0 service-account.json   # Linux
base64 -i service-account.json | tr -d '\n'   # macOS

{
  "mcpServers": {
    "mcp-gdocs": {
      "command": "npx",
      "args": ["-y", "mcp-gdocs"],
      "env": {
        "CREDENTIALS_CONFIG": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIs..."
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-gdocs": {
      "command": "npx",
      "args": ["-y", "mcp-gdocs"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

Method B: OAuth 2.0

For personal use with interactive browser login.

{
  "mcpServers": {
    "mcp-gdocs": {
      "command": "npx",
      "args": ["-y", "mcp-gdocs"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Multiple Google Accounts

GOOGLE_MCP_PROFILE isolates token storage per profile:

~/.config/mcp-gdocs/
├── token.json              # default (no profile)
├── work/token.json         # GOOGLE_MCP_PROFILE=work
└── personal/token.json     # GOOGLE_MCP_PROFILE=personal

Environment Variables

Known Limitations

• SA without Workspace: Service account without Google Workspace license has Drive quota = 0 and cannot create files. Use OAuth or impersonation.
• Comment anchoring: Programmatically created comments may not be anchored to text in Google Docs UI (Drive API limitation).
• Deeply nested lists: Lists with 3+ nesting levels may have formatting artifacts when converting Markdown.
• Paragraph style safe range: paragraph and heading style tools automatically adjust ranges to prevent styles from bleeding into adjacent paragraphs.

Troubleshooting

• Server won't start: check that environment variables are set in the MCP config env block.
• Authorization errors: make sure Docs and Drive APIs are enabled in Google Cloud Console. For OAuth — check that your email is added as Test User.
• Re-authorization: delete ~/.config/mcp-gdocs/token.json and run npx -y mcp-gdocs auth again.

Changelog · License