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