google-doc-claude
anaypaul/google-doc-claude
Read, write & add true inline (anchored) comments to Google Docs from Claude Code — an MCP server + CLI (Playwright).
Instalação
npx convez-ai anaypaul/google-doc-claude1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
google-doc-claude
Read, write, and comment on a Google Doc programmatically — including true inline / anchored comments (the kind you get by selecting text and choosing "Comment"), which no public Google API can create.
New here? See the User Guide for step-by-step setup and how to use it from Claude Code, the CLI, or as a library.
How it works
| Capability | Mechanism |
|---|---|
| Read doc text | Google Docs API (documents.get) |
| Edit / append / find-replace | Google Docs API (documents.batchUpdate) |
| Document-level (unanchored) comments | Google Drive API (comments.create) |
| Inline / anchored comments | Browser automation of the real Docs UI (Playwright) |
| Create tabs + author content | Browser automation |
Why anchored comments need a browser
The Drive API's comments.create accepts an anchor field, but for Google Docs
editor files the anchor is silently ignored — the comment becomes document-level.
The native anchor uses Google's undocumented internal kix.* format that has
never been reverse-engineered. Since 2021 the Docs body is painted to a
<canvas>, so there are also no DOM nodes to select.
The only reliable way to create an anchored comment is the human UI path, which this library automates:
- Find-then-select —
Cmd/Ctrl+F, type the exact target text,Enter,Escape. This moves the real document selection onto the match. (Synthetic JS events are rejected as untrusted; Playwright's native input is trusted and accepted.) - Comment —
Cmd+Option+M/Ctrl+Alt+Mopens the comment box (normal DOM), type the comment, submit withCmd/Ctrl+Enter. - Verify — the resulting thread carries Google's
docos-anchoreddocoviewclass, confirming it anchored to the selected range.
Setup
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
python -m playwright install chromium
# One-time: log into your Google account in the browser window that opens.
python main.py login
By default the tool drives your system Google Chrome (GDOC_CHANNEL=chrome); if
Chrome isn't installed it falls back to the bundled Chromium — which is why we run
python -m playwright install chromium.
The headline features — anchored comment, read, login — need only the browser
session (no client_secret.json). The API features (append, replace,
doc-comment, list-comments) additionally need a Google Cloud OAuth client:
- In Google Cloud Console, enable the Google Docs API and Google Drive API.
- Configure the OAuth consent screen (User type External; add your own Google account under Test users).
- Create an OAuth client ID of type Desktop app, download it, and save it
as
client_secret.jsonin the repo root. - The first API command opens a browser for one-time consent and writes
token.json. You'll see a "Google hasn't verified this app" screen — that's expected for your own personal OAuth client; choose Advanced → Go to google-doc-claude.
The OAuth client requests the Docs and full Drive scopes — full Drive is needed to comment on docs you didn't create. The browser features (
comment,read,login) request no API scopes.
Usage
# Browser features (need only `login`)
python main.py comment "<doc-url>" --target "exact phrase in the doc" --text "my note"
python main.py comment "<doc-url>" --target "phrase" --text "note" --tab "Chapter 2"
python main.py read "<doc-url>"
# API features (need client_secret.json)
python main.py append "<doc-url>" --text "appended line"
python main.py replace "<doc-url>" --find "TODO" --replace "DONE"
python main.py list-comments "<doc-url>"
Use it from Claude Code (MCP server)
The repo ships an MCP server so Claude Code can comment on any doc you have
access to, just by asking. Tools: gdoc_comment, gdoc_read,
gdoc_list_comments, gdoc_login, gdoc_status.
One-time setup:
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
python -m playwright install chromium
Register the server for this project by copying the template and filling in your absolute paths:
cp .mcp.json.example .mcp.json
# edit .mcp.json: set both paths to this repo's .venv/bin/python and
# gdocclaude/mcp_server.py (.mcp.json is gitignored — it's machine-specific)
Claude Code will prompt to approve the gdoc server — approve it. Then, in any
session:
You: Sign me in to Google for docs.
Claude: → gdoc_login() # log into the browser window that opens (once)
You: In <doc-url>, add the comment "nice result" on the text "28.4 BLEU".
Claude: → gdoc_comment(doc_url="<doc-url>", target="28.4 BLEU", comment="nice result")
→ {ok: true, anchored: true}
All docs share one logged-in browser profile (.browser-profile/), kept warm by a
single worker thread for speed. To run the server standalone: python gdocclaude/mcp_server.py (first time: python gdocclaude/mcp_server.py login).
Headless is off by default (the canvas editor is more reliable headed); set
GDOC_HEADLESS=1 to override.
Library
from gdocclaude.anchored import GoogleDocsCommenter
commenter = GoogleDocsCommenter()
with commenter.session() as s:
s.open_doc("https://docs.google.com/document/d/<ID>/edit")
res = s.comment_on_text("exact phrase in the doc", "Great point here.")
print(res.ok, res.anchored) # -> True True
# also: s.add_tab(title), s.type_in_body(text), s.switch_to_tab(title),
# s.delete_comments_matching(substring), s.delete_tab_by_title(title)
Reliability
The end-to-end test (scripts/e2e_tabs_comments.py) builds a tab for each of 12
landmark LLM papers (Attention Is All You Need, BERT, GPT-3, Chain-of-Thought, …),
types each summary, and posts a verified anchored comment on 36 target phrases.
Every comment is confirmed anchored via the docos-anchoreddocoview oracle.
Project layout
gdocclaude/
auth.py OAuth2 desktop flow (Docs + Drive scopes)
docs_api.py read / write / unanchored comments (official APIs)
anchored.py browser automation: tabs, selection, anchored comments, cleanup
mcp_server.py MCP server (warm browser worker) exposing gdoc_* tools
.mcp.json.example template for registering the MCP server (copy to .mcp.json)
main.py CLI
scripts/ login, exploratory probes, reliability + e2e tests
data/papers.json generated LLM-paper test dataset
Caveats
Browser automation tracks an undocumented, frequently-changing UI; selectors live
in anchored.py and may need updates if Google changes the Docs UI. Keyboard
shortcuts are used wherever possible because they're more stable than selectors.
Use only on your own account. Treat .browser-profile/ and token.json as
secrets (they are gitignored).