gdocs-mcp

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

Tools (28)

Google Docs — Read & Write

| Tool | Description | |------|-------------| | read_document | Read the full content of a Google Doc | | search_documents | Search Google Drive for documents by name, content, or date | | create_document | Create a new Google Doc with optional Markdown content | | replace_all_text | Find and replace all occurrences of text in a document | | replace_image | Replace an existing image with a new image from a URI | | update_document_markdown | Replace the entire document body with Markdown | | update_document_section_markdown | Insert or replace a section by index with Markdown | | update_document_style | Update page size, margins, text direction | | update_document | Raw batchUpdate with 35+ request types | | unmerge_table_cells | Unmerge previously merged table cells |

Content Insertion

| Tool | Description | |------|-------------| | insert_image | Insert an image from a URL with optional width/height sizing | | insert_table | Create a table with specified rows (1-20) and columns (1-20) | | insert_page_break | Insert a page break at a specific position | | insert_link | Add a hyperlink to an existing text range |

Document Management

| Tool | Description | |------|-------------| | export_document | Export as PDF, DOCX, TXT, or HTML. Save to file or return base64 | | copy_document | Duplicate a doc with a new title. Great for templates | | delete_document | Move to trash. Requires exact title confirmation to prevent accidents |

Comments

| Tool | Description | |------|-------------| | get_comments | List comments with author, content, resolved status, and replies | | add_comment | Add a comment anchored to specific text in the document |

Style Presets

Define how your documents look once, apply everywhere.

| Tool | Description | |------|-------------| | extract_document_styles | Extract styles from a reference Google Doc and save as a reusable preset | | apply_style_preset | Apply a style preset to any document — fonts, colors, spacing, tables | | list_style_presets | List all available presets (4 built-in + your custom presets) | | set_active_preset | Set the default preset for new documents | | delete_style_preset | Delete a custom preset |

Formatting

| Tool | Description | |------|-------------| | update_header_footer | Create or update header/footer content and styling | | format_list | Apply bullet, numbered, or remove list formatting (6 glyph presets) |

Google Sheets

| Tool | Description | |------|-------------| | get_charts | List all charts in a spreadsheet with IDs and specs |

Automation

| Tool | Description | |------|-------------| | execute_script | Run a function in a deployed Google Apps Script project |

Style Presets

Built-in Presets

| Preset | Font | Headings | Body | |--------|------|----------|------| | clean | Inter | Dark charcoal, 22/16/13pt | 11pt, 1.5x spacing | | corporate | Arial | Dark grey, conservative | 11pt, 1.4x spacing | | classic | Georgia + Garamond | Dark blue, serif | 11pt, 1.4x spacing | | minimal | Roboto | Black, light weight | 10.5pt, 1.5x spacing |

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

| Scope | Tools | |-------|-------| | documents | read, create, replace, update, insert image/table/link/page break, style presets, header/footer, format list | | spreadsheets.readonly | get_charts | | drive | search, export, copy, delete, get/add comments |

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:

| Variable | Effect | |----------|--------| | GDOCS_CREDENTIALS | Override credentials.json path | | GDOCS_MCP_READONLY | Set to 1 to disable write tools (export, copy, delete, comments) | | GDOCS_MCP_QUIET | Set to 1 to disable performance logging |

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