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:

• Service Account — for automation, CI, servers
• OAuth — for personal documents

See the Authentication section below for details.

2a. Service Account — share your documents

Share the documents/folders with the service account email (client_email from the JSON key).

2b. OAuth — authorize

GOOGLE_CLIENT_ID="your-client-id" \
GOOGLE_CLIENT_SECRET="your-client-secret" \
npx -y mcp-gdocs auth

A browser window will open for Google authorization. The refresh token is saved to ~/.config/mcp-gdocs/token.json.

3. Add to Cursor / MCP Client

Service Account:

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

OAuth:

{
  "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

Batch Operations

The batch update tool combines multiple heterogeneous operations into a single API request. This helps with the per-minute quota (60 write ops/min) during bulk formatting. Large arrays are automatically split into chunks.

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 → ADC.

Service Account vs OAuth

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:

A1. SERVICE_ACCOUNT_PATH (+ impersonation)

{
  "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"
      }
    }
  }
}

A2. CREDENTIALS_CONFIG — Base64-encoded JSON (Docker / CI / K8s)

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..."
      }
    }
  }
}

A3. GOOGLE_APPLICATION_CREDENTIALS

{
  "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.

Step 1: Create OAuth Client

1. Google Cloud Console → APIs & Services → Credentials
2. Create OAuth client ID → Desktop app
3. Copy Client ID and Client Secret
4. OAuth consent screen → add your email as Test User

Step 2: Authorize

GOOGLE_CLIENT_ID="your-client-id" \
GOOGLE_CLIENT_SECRET="your-client-secret" \
npx -y mcp-gdocs auth

Step 3: MCP configuration

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

Method C: Application Default Credentials (ADC)

Ideal for Google Cloud environments (GKE, Compute Engine, Cloud Run) and local development with gcloud.

ADC is used automatically as a fallback when no other methods are configured.

For local development:

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/documents,https://www.googleapis.com/auth/drive

For Google Cloud: attach a service account to the compute resource — no extra variables needed.

Multiple Google Accounts (Profiles)

GOOGLE_MCP_PROFILE isolates token storage per profile:

{
  "mcpServers": {
    "mcp-gdocs-work": {
      "command": "npx",
      "args": ["-y", "mcp-gdocs"],
      "env": {
        "GOOGLE_CLIENT_ID": "...",
        "GOOGLE_CLIENT_SECRET": "...",
        "GOOGLE_MCP_PROFILE": "work"
      }
    },
    "mcp-gdocs-personal": {
      "command": "npx",
      "args": ["-y", "mcp-gdocs"],
      "env": {
        "GOOGLE_CLIENT_ID": "...",
        "GOOGLE_CLIENT_SECRET": "...",
        "GOOGLE_MCP_PROFILE": "personal"
      }
    }
  }
}

Tokens are stored separately:

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

Token Storage

OAuth refresh tokens are stored in ~/.config/mcp-gdocs/token.json (respects XDG_CONFIG_HOME). To re-authorize, run npx -y mcp-gdocs auth again or delete the token file.

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 appear in the list but 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 (GOOGLE_CLIENT_ID / GOOGLE_APPLICATION_CREDENTIALS) are set in the MCP config env block.
• Authorization errors: make sure Docs API and Drive API are enabled in Google Cloud Console. For OAuth — check that your email is added as Test User in OAuth consent screen.
• Re-authorization: delete ~/.config/mcp-gdocs/token.json and run npx -y mcp-gdocs auth again.

Changelog

License