google-docs-mcp - Google Docs MCP that actually works

The framing in the README is the right one to lead with. Google Docs' API uses character indices for every edit. LLMs are bad at counting characters. The result, in every "Google Docs MCP" project that came before this one: agents end up deleting and rewriting entire documents, which destroys version history, comments, and collaborator attribution.

google-docs-mcp uses the same abstraction as code editors: search by text, not by position. You describe what to change; the server finds where it is and handles the index arithmetic. That single design choice fixes the broken existing options.

Quick start

The fastest path is uvx, which downloads the package, creates an isolated environment, installs deps, and runs the entry point in one shot:

uvx --from git+https://github.com/dbuxton/google-docs-mcp google-docs-mcp --help

For a persistent install:

uv tool install --from git+https://github.com/dbuxton/google-docs-mcp google-docs-mcp
uv tool install --from git+https://github.com/dbuxton/google-docs-mcp google-docs-mcp-auth

You'll need a Google Cloud OAuth app:

1. Create a project in Google Cloud Console.
2. Enable Google Docs API, Google Drive API, and (for inline-anchored comments) Google Apps Script API.
3. Create a Desktop OAuth 2.0 Client ID, download the JSON.

Then authenticate:

uvx --from git+https://github.com/dbuxton/google-docs-mcp \
  google-docs-mcp-auth --credentials ~/credentials.json

The --headless flag prints a URL you can open on a different device (phone, laptop) for SSH and remote-server setups. Token saves to ~/.google-docs-mcp/token.json by default.

Wire it into Claude Desktop

{
  "mcpServers": {
    "google-docs": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dbuxton/google-docs-mcp", "google-docs-mcp"],
      "env": {
        "GOOGLE_DOCS_MCP_TOKEN": "/Users/you/.google-docs-mcp/token.json"
      }
    }
  }
}

Same shape works for any MCP-aware client. For local development, swap the git+... URL for an absolute path to your checkout.

The tools that matter

The whole interface is text-anchor based. You never deal with character indices.

docs_search_replace(doc_id, find, replace, occurrence, regex) - the workhorse. Replace a specific occurrence (or all of them with occurrence=0), with optional regex support:

docs_search_replace(doc_id="...", find="Q1 2024", replace="Q2 2024")
docs_search_replace(doc_id="...", find="ACME Corp", replace="Initech", occurrence=0)
docs_search_replace(doc_id="...", find=r"\bDraft\b", replace="Final", regex=true)

docs_insert_after(doc_id, anchor, text) and docs_insert_before(...) - insert a new paragraph relative to the paragraph containing the anchor text. Same shape as "above the Executive Summary heading" in plain English.

docs_delete_paragraph(doc_id, anchor) - delete all paragraphs containing the anchor text (case-insensitive). Useful for [PLACEHOLDER - DELETE ME] markers in templates.

docs_append(doc_id, text) - append a new paragraph at the end. The simplest case.

docs_batch_replace(doc_id, replacements_json) - apply multiple find/replace operations atomically in a single API call. Either all changes succeed or none do. Use this whenever you're making more than one edit; it preserves the doc's coherence even if one of the changes fails validation.

docs_get(doc_id) - read the document. Returns title, paragraphs (with text, heading style, and character indices), and full plain text. The character indices are returned for completeness, but the editing tools don't need them - they're useful for when the agent wants to understand structure before editing.

docs_list(query, limit) - search and list Drive docs. Optional query string searches both title and content.

Why version history matters

The implicit feature you don't notice until something breaks: every edit is a precise mutation, not a rewrite. Google Docs version history shows exactly what changed. Comments stay anchored to the right text. Collaborator attribution is preserved.

If you've used a worse Google Docs MCP and watched it nuke a doc and re-upload it, you know how badly the alternatives degrade the actual collaboration surface. This is the version that doesn't do that.

The Apps Script bridge for bookmark comments

There's an optional one-time setup for docs_add_comment(..., bookmark_jump=true) that adds a real #bookmark=id... jump URL into a comment. It involves enabling the Apps Script API, creating a standalone Apps Script project as a bridge, and switching the bridge to the same Google Cloud project as your OAuth client. Skip it unless you're going to use bookmark-jumping comments specifically.

Suggestion mode handling

A subtle but useful detail: when the MCP reads document content before planning index-based edits, it requests suggestionsViewMode=SUGGESTIONS_INLINE. That keeps returned indices aligned for later documents.batchUpdate calls when the doc contains suggestions, which is the kind of edge case that breaks naive implementations.

When to reach for it

• You want agents to edit Google Docs without destroying version history or comments.
• You manage a templated workflow (proposals, board decks, project briefs) where the agent fills in or updates specific named sections.
• You need atomic multi-edit operations - reroll the whole batch or reroll nothing.

When not to

• One-shot doc creation. The Google Docs API is fine for "create a new doc with this content"; you don't need the search-by-anchor abstraction.
• Workloads where you specifically need character-precise programmatic edits (rare; this is what the index-based API was designed for).

Trade-offs and limits

The tool is standalone - no other MCPs required, just the Google Cloud OAuth app. Auth has reasonable resolution order: --credentials flag, then --client-id/--client-secret flags, then GOOGLE_DOCS_MCP_CLIENT_ID/GOOGLE_DOCS_MCP_CLIENT_SECRET env vars.

There's a google-drive-mcp legacy alias for backward compatibility (the project was renamed). New setups should use google-docs-mcp everywhere.

The Apps Script bridge is optional but adds real overhead if you want it. Skip on first install.

For agents writing structured docs at scale, this is the MCP to standardise on. The text-anchor abstraction sounds small but it's the difference between "Google Docs editing actually works" and "Google Docs editing destroys your version history."