convez.ai
MCP Server
anaypaul

google-doc-claude

anaypaul/google-doc-claude

Ver no GitHub
InicialPluginScore · de 0 a 100

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-claude

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

CapabilityMechanism
Read doc textGoogle Docs API (documents.get)
Edit / append / find-replaceGoogle Docs API (documents.batchUpdate)
Document-level (unanchored) commentsGoogle Drive API (comments.create)
Inline / anchored commentsBrowser automation of the real Docs UI (Playwright)
Create tabs + author contentBrowser 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:

  1. 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.)
  2. Comment — Cmd+Option+M / Ctrl+Alt+M opens the comment box (normal DOM), type the comment, submit with Cmd/Ctrl+Enter.
  3. Verify — the resulting thread carries Google's docos-anchoreddocoview class, 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:

  1. In Google Cloud Console, enable the Google Docs API and Google Drive API.
  2. Configure the OAuth consent screen (User type External; add your own Google account under Test users).
  3. Create an OAuth client ID of type Desktop app, download it, and save it as client_secret.json in the repo root.
  4. 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).

License

MIT

Ver o original no GitHub

Bom para

Relacionados