gdocs-mcp

Open-source MCP server for Google Docs and Sheets. Give Claude (or any MCP-compatible AI) the ability to read, create, edit, style, export, and collaborate on your Google Docs — with OAuth tokens that never leave your machine.

Open-source. Self-hosted. Your tokens never leave your machine.

Quick Start

1. Set up Google Cloud credentials (one-time)

1. Go to Google Cloud Console

2. Create a project (or use an existing one)

3. Enable the Google Docs API, Google Sheets API, and Google Drive API

4. Go to Google Auth Platform > Audience, set to External, add yourself as a test user

5. Go to Credentials > Create Credentials > OAuth client ID > Desktop app

6. Download the JSON file

2. Authenticate

npx gdocs-mcp auth ~/Downloads/client_secret_*.json

This opens your browser for Google sign-in, saves the token to ~/.gdocs-mcp/, and prints the MCP config.

3. Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "gdocs": {
      "command": "npx",
      "args": ["gdocs-mcp"]
    }
  }
}

Restart Claude Desktop. Ask Claude: "List my recent Google Docs" to verify.

Add to Claude Code

claude mcp add gdocs -- npx gdocs-mcp

Related MCP server: Google Workspace MCP Server

Tools (28)

Google Docs — Read & Write

Content Insertion

Document Management

Comments

Style Presets

Define how your documents look once, apply everywhere.

Formatting

Google Sheets

Automation

Style Presets

Built-in Presets

Extract + Apply Workflow

Point to a Google Doc that already looks the way you want:

You: "Extract styles from my brand doc and save as 'brand'"
  → extract_document_styles(documentId, saveAs: "brand")

You: "Apply brand styles to this report"
  → apply_style_preset(documentId, presetName: "brand")

One-step capture, one-step apply. No JSON editing needed.

Style Properties

Presets support every text and paragraph property the Google Docs API exposes:

Text: font family, font size, bold, italic, underline, strikethrough, small caps, text color, background color, baseline offset

Paragraph: alignment (left/center/right/justified), line spacing, space above/below, first line indent, start/end indent, keep lines together, keep with next, direction (LTR/RTL), paragraph borders

Document: page margins, page size

Tables: header row background and text color, bold headers, border color and width, cell padding, alternating row backgrounds

Only properties you specify are applied. Omitted properties are left unchanged. Config stored at ~/.gdocs-mcp/styles.json.

Upgrading to v0.4

v0.4 expands the Drive scope from drive.readonly to drive (needed for export, copy, delete, and comments). You must re-authenticate:

npx gdocs-mcp auth

If you don't need the new tools and want to keep the old scope:

GDOCS_MCP_READONLY=1 npx gdocs-mcp

Scope Justification

Limitations

These are Google Docs API limitations, not gdocs-mcp limitations:

• Table of Contents styling is not controllable — TOC entries mirror heading styles

• Custom named styles cannot be created — only the 9 built-in types (Title, Subtitle, Heading 1-6, Normal Text)

• Conditional formatting does not exist in Google Docs

• Multi-column layout is not exposed via the API

• Table header detection assumes row 0 is the header — multi-row headers are not detected

• Suggested edits (propose mode) are not yet supported

• Comment replies are not yet supported — only top-level comments

• Image URLs are passed directly to Google's API — the MCP server does not fetch them

Performance Logging

Every tool call logs latency to stderr:

[gdocs-mcp] read_document: 342ms (api: 298ms)
[gdocs-mcp] apply_style_preset: 1247ms (api: 1102ms, 1593 requests)
[gdocs-mcp] list_style_presets: 2ms (local)

Disable with GDOCS_MCP_QUIET=1.

Security

• OAuth tokens stored locally at ~/.gdocs-mcp/token.json with 600 permissions

• Credentials stored at ~/.gdocs-mcp/credentials.json with 600 permissions

• Style presets stored at ~/.gdocs-mcp/styles.json

• No telemetry, no data collection, no third-party token storage

• Tokens refresh automatically; if refresh fails, run npx gdocs-mcp auth again

• delete_document requires exact title match — not a boolean flag

Configuration

Credentials and tokens stored in ~/.gdocs-mcp/ by default. Override with:

GDOCS_CREDENTIALS=/path/to/credentials.json npx gdocs-mcp

Environment variables:

For faster startup, install globally:

npm install -g gdocs-mcp

Requirements

• Node.js 18+

• A Google Cloud project with Docs, Sheets, and Drive APIs enabled

License

MIT