GitHub - dbuxton/google-docs-mcp: Surgical Google Docs editing for AI agents — search/replace, insert, comments, and more. MCP server.

Surgical Google Docs editing for AI agents — preserves history, never touches character indices.

An MCP server that makes Google Docs actually usable for LLMs. Standalone — no other tools required beyond a Google Cloud OAuth app.

Compatibility note: the repo, package, CLI, env vars, and default token path now use google-docs-mcp. Backward-compatible google-drive-mcp command and env-var aliases are still accepted so existing setups do not break immediately.

Indexing note: 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.

Why

The Google Docs API uses character indices for every edit. LLMs are bad at counting characters. Everyone ends up deleting and rewriting entire documents, which destroys version history, comments, and collaborator attribution.

This server 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.

Quick start

1. Run directly from GitHub

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

That command downloads the package, creates an isolated environment, installs dependencies, and runs the google-docs-mcp entry point.

No PyPI release is required. uvx can execute the tool straight from the GitHub repository.

To pin to a branch, tag, or commit, add a ref to the URL:

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

If you prefer a persistent local install instead of uvx, use:

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

2. Create a Google Cloud OAuth app

1. Go to console.cloud.google.com
2. Create a project (or select an existing one)
3. Enable these APIs (APIs & Services → Library):
   • Google Docs API
   • Google Drive API
   • Google Apps Script API (for inline-anchored comments)
4. Go to APIs & Services → Credentials
5. Click Create Credentials → OAuth 2.0 Client ID
6. Application type: Desktop App
7. Download the JSON file

3. Authenticate

Normal — browser opens automatically:

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

Or use env vars instead of a credentials file:

export GOOGLE_DOCS_MCP_CLIENT_ID="your-google-client-id"
export GOOGLE_DOCS_MCP_CLIENT_SECRET="your-google-client-secret"

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

Headless / remote server — no browser on device:

uvx --from git+https://github.com/dbuxton/google-docs-mcp \
  google-docs-mcp-auth --credentials ~/credentials.json --headless
# Prints a URL → open on any device (phone, laptop, etc.)
# Paste the full redirect URL back into the terminal

Already have an auth code:

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

google-docs-mcp-auth resolves OAuth client credentials in this order:

1. --credentials /path/to/credentials.json
2. --client-id and --client-secret
3. GOOGLE_DOCS_MCP_CLIENT_ID and GOOGLE_DOCS_MCP_CLIENT_SECRET

Token is saved to ~/.google-docs-mcp/token.json by default. Override with --out /path/to/token.json.

4. Configure your MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

OpenClaw (gateway config):

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

Local checkout during development:

{
  "mcpServers": {
    "google-docs": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/google-docs-mcp", "google-docs-mcp"],
      "env": {
        "GOOGLE_DOCS_MCP_TOKEN": "/Users/you/.google-docs-mcp/token.json"
      }
    }
  }
}

Optional: Apps Script bridge for bookmark-jump comments

If you want docs_add_comment(..., bookmark_jump=true) to append a real #bookmark=id... jump URL into the comment body, set up one persistent Apps Script bridge project and expose its script ID via an env var.

Required one-time setup:

1. Enable the Apps Script API for the Google account at https://script.google.com/home/usersettings
2. Create a standalone Apps Script project to use as the bridge
3. In that Apps Script project, open Project Settings and switch it to the same standard Google Cloud project as the OAuth client used by google-docs-mcp
4. In that same Google Cloud project, ensure Apps Script API is enabled
5. Set the bridge script ID in the MCP process environment:

export GOOGLE_DOCS_MCP_APPS_SCRIPT_ID="1C6nchmQRobIwK8ELFe29k-XV2t7mUnhKiSpEKHThXOFHAL6Ahy4_Xju4"

Example uvx launch with both token + Apps Script bridge:

GOOGLE_DOCS_MCP_TOKEN="$HOME/.google-docs-mcp/token.json" \
GOOGLE_DOCS_MCP_APPS_SCRIPT_ID="your-apps-script-id" \
uvx --from git+https://github.com/dbuxton/google-docs-mcp google-docs-mcp

If the Apps Script bridge is still using its hidden default project, scripts.run fails even when account-level Apps Script access is enabled.

Tools reference

Document reading

docs_get(doc_id)

Read a Google Doc and return its full structure.

Returns the document title, a list of paragraphs (with text, heading style, and character indices), and the full plain text. Use this first to understand the document before making edits.

docs_get(doc_id="1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms")

Returns:

{
  "title": "My Document",
  "paragraphs": [
    {"text": "Introduction", "style": "HEADING_1", "start": 0, "end": 13},
    {"text": "This is the body.", "style": "NORMAL_TEXT", "start": 13, "end": 31}
  ],
  "full_text": "Introduction\nThis is the body."
}

docs_list(query, limit)

List Google Docs from Drive, optionally filtered by a search query.

docs_list(query="board deck 2026", limit=5)

Document editing

All editing tools use text anchors, never character indices. The server finds the text and handles the indices internally.

docs_search_replace(doc_id, find, replace, occurrence, regex)

Find text in a document and replace a specific occurrence.

# Replace first occurrence
docs_search_replace(doc_id="...", find="Q1 2024", replace="Q2 2024")

# Replace all occurrences
docs_search_replace(doc_id="...", find="ACME Corp", replace="Initech", occurrence=0)

# Regex replace
docs_search_replace(doc_id="...", find=r"\bDraft\b", replace="Final", regex=true)

docs_insert_after(doc_id, anchor, text)

Insert a new paragraph immediately after the paragraph containing anchor.

docs_insert_after(
  doc_id="...",
  anchor="Executive Summary",
  text="Updated as of March 2026 following board review."
)

docs_insert_before(doc_id, anchor, text)

Insert a new paragraph immediately before the paragraph containing anchor.

docs_insert_before(
  doc_id="...",
  anchor="Appendix A",
  text="See the following appendix for supporting data."
)

docs_delete_paragraph(doc_id, anchor)

Delete all paragraphs containing anchor text (case-insensitive).

docs_delete_paragraph(doc_id="...", anchor="[PLACEHOLDER — DELETE ME]")

docs_append(doc_id, text)

Append a new paragraph at the end of the document.

docs_append(doc_id="...", text="Document last updated: March 2026.")

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.

docs_batch_replace(
  doc_id="...",
  replacements_json='[
    {"find": "[CLIENT]", "replace": "Acme Corp", "occurrence": 0},
    {"find": "[DATE]", "replace": "10 March 2026", "occurrence": 0},
    {"find": "DRAFT", "replace": "FINAL"}
  ]'
)

Each item in the array:

docs_create(title, initial_text)

Create a new Google Doc.

docs_create(title="Q2 Board Deck", initial_text="Confidential — not for distribution.")

Returns {id, title, webViewLink}.

Comments

docs_add_comment(doc_id, comment, anchor_text, occurrence, include_anchor_text, bookmark_jump)

Add a comment anchored to specific text in the document.

Use a short, distinctive phrase for anchor_text — a few words that are unique enough to match exactly one location.

docs_add_comment(
  doc_id="...",
  anchor_text="unable to perform the Employee's duties",
  comment="Legal risk: 3-month absence threshold may not satisfy Equality Act 2010 duty to make reasonable adjustments before terminating.",
  bookmark_jump=true
)

Note: The current implementation uses Drive comments plus a Docs named range. In the Docs UI these still show as "Original content deleted" rather than as proper inline highlights. The comments are fully readable via docs_read_comments and the Docs 💬 panel.

When bookmark_jump=true, the tool additionally uses Apps Script automation to create a bookmark at the anchor text and appends a #bookmark=id... jump URL into the comment body. This requires the GOOGLE_DOCS_MCP_APPS_SCRIPT_ID env var and the Apps Script bridge setup documented above.

A probe helper is included for this workstream:

python3 appscript_probe.py inspect-comment-api --doc-id <DOC_ID>

The probe now creates an API-executable deployment automatically. If account-level Apps Script access is still disabled, it stops with the settings-page message. If execution fails with a permission error, the next blocker is the shared standard Google Cloud project requirement documented at https://developers.google.com/apps-script/guides/cloud-platform-projects.

docs_read_comments(doc_id, include_resolved)

List all comments on a document.

Returns an array of comments with id, content, author, anchored (bool), named_range_id, quoted_text, resolved, deleted, created.

docs_read_comments(doc_id="...")

docs_reply_to_comment(doc_id, comment_id, reply)

Post a reply to an existing comment.

docs_reply_to_comment(
  doc_id="...",
  comment_id="AAAB1iPyaUY",
  reply="Agreed — adding Carer's Leave clause before we sign."
)

docs_resolve_comment(doc_id, comment_id, reply)

Resolve (close) a comment, optionally posting a final reply first.

docs_resolve_comment(
  doc_id="...",
  comment_id="AAAB1iPyaUY",
  reply="Fixed in v2 — carer's leave clause added at 15.1."
)

docs_delete_comment(doc_id, comment_id)

Permanently delete a comment.

docs_delete_comment(doc_id="...", comment_id="AAAB1iPyaUY")

Typical workflows

Contract review

1. docs_get          — read the document
2. docs_add_comment  — flag issues with anchor_text pointing to specific clauses
3. docs_read_comments — audit what's been flagged
4. docs_search_replace — fix straightforward issues directly
5. docs_resolve_comment — close comments as they're addressed

Bulk document update

1. docs_list         — find all relevant documents
2. docs_batch_replace — apply changes atomically (e.g. rebrand, date update)
3. docs_get          — verify the result

Collaborative review

1. docs_add_comment  — add review notes
2. docs_reply_to_comment — respond to collaborator comments
3. docs_resolve_comment  — close resolved threads

Auth environment variables

Legacy GOOGLE_DRIVE_MCP_* env var aliases still work for backward compatibility.

Scopes

The auth setup requests these scopes:

License

MIT