gdocs-patch

Efficient Google Doc editing for agents

Overview

When you ask an agent to edit a Google Doc, they would typically need to assemble Google Docs API requests manually. This involves finding the right order of operations, managing document indices, and keeping track of styles. It is all quite error-prone and could lead to data loss if the agent makes a mistake.

gdocs-patch is a CLI and MCP that allows agents to efficiently edit Google documents by representing documents as XHTML and allowing the agent to make targeted edits, just like editing a normal file locally.

Install

Install the CLI with uv:

uv tool install gdocs-patch

Alternatively, install it with pip:

pip install gdocs-patch

gdocs-patch supports Python 3.10 and newer.

How it works

gdocs-patch exposes a few commands for agents to use:

read    Read a Google document as canonical XHTML.
edit    Edit exact text in canonical XHTML.
write   Write canonical XHTML to a Google document.
syntax  Explore the XHTML document syntax.
skill   Show best practices for coding agents using gdocs-patch.
auth    Manage Google authentication.

The editing commands (read, edit, and write) all operate using a custom XHTML dialect that represents every Google doc element as a tag or attribute. The agents can learn the dialect by reading documents, or through the syntax and skill commands.

gdocs-patch at its core is a source doc + target doc = google doc batch update request compiler. The agent reads the source document, edits the XHTML locally, and calls write to apply the edits to the Google Doc. Alternatively, agents can call edit to make targeted replacements without a local copy.

Authenticating with Google

You need to give the tool access to the Google Docs API. To do this, create a Google Cloud project, enable the Google Docs API in the project, configure its OAuth consent screen, and create an OAuth client with application type Desktop app. Download its client JSON and save it in ~/.config/gdocs-patch/client_secret.json:

mkdir -p ~/.config/gdocs-patch
cp ~/Downloads/client_secret.json ~/.config/gdocs-patch/client_secret.json

The client_secret.json file allows gdocs-patch to log you in via OAuth.

gdocs-patch auth login

This command opens the OAuth authorization screen. Authorize the app. Once done, gdocs-patch should say you're good to go.

If you need to run the tool non-interactively, you can copy the OAuth authorization URL from the terminal and paste it into your local browser. After finishing authorization, copy the complete callback URL from your browser's address bar and paste it back into the terminal.

MCP server

A Streamable HTTP MCP server is also available that exposes the read, edit, and write commands over MCP. To use it, install gdocs-patch[mcp]:

uv tool install 'gdocs-patch[mcp]'

The server uses the same Google credentials as the CLI.

The MCP server is secured via a static Bearer token. Generate a token and set it to the GDOCS_PATCH_MCP_TOKEN environment variable. Then start the server with gdocs-patch-mcp:

export GDOCS_PATCH_MCP_TOKEN="$(openssl rand -hex 32)"
gdocs-patch-mcp --host 127.0.0.1 --port 8000

Every request must include Authorization: Bearer with the value of GDOCS_PATCH_MCP_TOKEN. There's no built-in TLS, though, so you'd still need your own reverse proxy and potentially more security if you want to expose the MCP server over the open internet.

Google Docs support

This table shows what you can currently change with gdocs-patch and whether the Google Docs batchUpdate API provides enough support for the feature.

• ✅ Supported
• ⚠️ Supported with limitations
• ❌ Unsupported

Development

Install Python 3.14 and synchronize all development dependencies:

uv sync --dev --all-extras

Run the test and static-analysis tools:

uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run fixit lint .
uv run pyright

Install and run the Git hooks:

uv run pre-commit install
uv run pre-commit run --all-files

See RELEASING.md for package build, versioning, and PyPI publication instructions.

License

MIT