gdocs-comments-mcp

Inline, range-anchored comments for Google Docs — the one comment operation the Google APIs can't do.

_{Quickstart  ·  Scope  ·  Tools  ·  Configuration  ·  How it works  ·  Troubleshooting  ·  Server deployment  ·  FAQ}

You're building an AI process around Google Docs — an agent that reviews drafts, audits contracts, gives editorial feedback. The natural way to deliver that feedback is how humans do it: a comment pinned to the exact sentence it's about, not a wall of text dumped at the end of the doc or into chat.

Then you hit the wall: the Google APIs can't create anchored comments. The Docs API has no comment endpoints at all, and the Drive API accepts an anchor field only to have the Docs editor ignore it — the comment shows up as a general, whole-document comment.

This MCP server closes that gap. Your agent calls add_comment with a text fragment and a comment; the server posts it through a real, logged-in Google Docs session, so it lands anchored to that exact text — just as if a human had selected it and pressed Ctrl+Alt+M:

Why not the official APIs?

This server does one thing: add a comment to a Google Doc. The interesting case is the anchored one — a comment pinned to a specific text range — which no Google API can do.

The Docs API has no comment endpoints at all. The Drive API's comments.create accepts an anchor field, but the Docs editor ignores it — the comment renders as an unanchored, whole-document comment. The editor's own anchor format (kix.*) is undocumented and can't be produced externally (Drive API docs, issuetracker #292610078, open since 2016). Driving the editor UI is the only way — so this server does exactly that, and nothing else. (Listing, replying, resolving, and deleting comments already work over the Drive API — use a Drive-based tool for those.)

What this does — and what it doesn't

This server is deliberately one narrow thing. Read this before wiring it in.

✅ It does: add comments to a Google Doc — anchored to a specific text range (the part no API can do), or unanchored on the whole document.

❌ It does NOT:

Important: this tool never returns document content — its output is structured-only ({ ok, anchored, occurrence_used, verified }), by design, so a malicious doc can't inject instructions into your agent. That means the agent is writing blind: to review a doc intelligently, pair this with a read capability (Docs API documents.get) and feed the exact quoted text back in as find_text. The two use different auth — this server drives a logged-in browser session (no OAuth), while the Docs/Drive APIs need an OAuth token or service account — but they can run against the same Google account.

Quickstart

One command — signs you in (opens a browser once), then registers the server with Claude Code:

npx -y gdocs-comments-mcp setup

That's it — skip to Use it below. Prefer to do it by hand, or use another client? The manual steps are below.

npx -y gdocs-comments-mcp login

# Claude Code
claude mcp add gdocs-comments -- npx -y gdocs-comments-mcp

{
  "mcpServers": {
    "gdocs-comments": {
      "command": "npx",
      "args": ["-y", "gdocs-comments-mcp"]
    }
  }
}

{
  "mcpServers": {
    "gdocs-comments": {
      "command": "npx",
      "args": ["-y", "gdocs-comments-mcp"]
    }
  }
}

{
  "mcpServers": {
    "gdocs-comments": {
      "command": "npx",
      "args": ["-y", "gdocs-comments-mcp"]
    }
  }
}

{
  "servers": {
    "gdocs-comments": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "gdocs-comments-mcp"]
    }
  }
}

3. Use it — ask your agent:

Add a comment to https://docs.google.com/document/d/1AbC…/edit — anchor it to "quarterly numbers" and say "Update this before Friday".

The agent calls add_comment and gets back:

{ "ok": true, "anchored": true, "occurrence_used": 1, "verified": true }

…and the comment is sitting on the highlighted phrase in the doc, from the account you logged in with.

No Playwright browser download is needed — by default the server drives your installed Google Chrome via playwright-core.

Tools

add_comment

Returns { ok, anchored, occurrence_used, verified } — verified: true means the posted comment was observed in the page after submitting. If find_text is given but not found, the call fails with TEXT_NOT_FOUND and nothing is posted.

The tool never returns document content, so a malicious doc can't inject instructions into your agent through it.

check_connection

Probes the Google session; returns { connected, mode }. If connected: false, run npx gdocs-comments-mcp login again.

Scope note: this server does one thing — creating anchored comments. Listing, replying, resolving, and deleting comments all work fine through the Drive API (comments.*), which is faster and needs no browser — use a Drive-based MCP for those.

CLI

npx gdocs-comments-mcp login    # one-time interactive Google sign-in
npx gdocs-comments-mcp status   # is the saved session still valid?
npx gdocs-comments-mcp logout   # delete the saved session/profile

Configuration

All optional, via environment variables:

Troubleshooting

First run on a new machine? npx gdocs-comments-mcp status tells you exactly where you stand.

Running on a server / datacenter IP

On a residential machine the default profile mode just works. On datacenter IPs, Google's anti-fraud rejects a freshly launched browser process reusing a saved session — it bounces to accounts.google.com/confirmidentifier. Relaunching from a profile does not work there.

What does work: keep the exact browser the operator logged into alive, and let this server attach to it:

1. Start a long-lived Chrome/Chromium (under Xvfb if headless) with --remote-debugging-port=9333 and log in to Google inside it once.
2. Run the MCP server with GDOCS_COMMENTS_CDP_URL=http://127.0.0.1:9333.

The server then drives that live session over CDP and never launches its own browser. Keep the session warm by navigating it to docs.google.com every few hours, or an idle session expires after ~1–2 weeks.

How it works

Because the APIs can't anchor a comment, the server does exactly what a person would: it drives the real Google Docs editor. Here's the full path of one add_comment call.

1. Attach to a logged-in browser. In the default profile mode, the server owns a persistent Chromium profile (your installed Google Chrome, via playwright-core — no extra browser download). You authenticate into it once with gdocs-comments-mcp login; the Google session cookies are saved to ~/.gdocs-comments-mcp/profile and reused headlessly on every later run. In CDP mode (GDOCS_COMMENTS_CDP_URL) the server instead attaches over the Chrome DevTools Protocol to a browser you keep alive — see server deployment.

2. Open the document. It navigates to https://docs.google.com/document/d/<id>/edit?hl=en. The doc id is validated first, and navigation is hard-pinned to docs.google.com — the tool can't be steered elsewhere. If the page bounces to accounts.google.com, the session is dead and the call returns SESSION_EXPIRED. ?hl=en pins the UI language so the find-bar counter is parseable in the next step.

3. Find the anchor text. The document body renders to an HTML <canvas>, not selectable DOM — so you can't just query for the text and click it. Instead the flow is entirely keyboard-driven (which also makes it locale- and CSS-class-independent):

Ctrl/Cmd+F  →  type find_text  →  read the "N of M" match counter

Reading the counter before commenting is the key safety step: if find_text has zero matches, or occurrence is larger than the match count, the call fails with TEXT_NOT_FOUND and nothing is posted — instead of the old failure mode where a blind key sequence would silently drop the comment wherever the cursor happened to sit.

4. Select the requested occurrence and comment. It presses Enter N times to land on the N-th match, Esc to close the find bar (leaving that occurrence selected), then:

Ctrl/Cmd+Alt+M  →  type comment_text  →  Ctrl/Cmd+Enter (submit)

Ctrl/Cmd+Alt+M is the Docs shortcut for "insert comment on the current selection" — which is precisely the anchored comment the APIs won't create. Keyboard shortcuts are chosen per-platform (Cmd on macOS, Ctrl elsewhere).

(If find_text is omitted, steps 3–4 collapse to "put the cursor at the document start and comment there" — a general, unanchored comment.)

5. Verify and report. After submitting, the server waits for the comment text to appear in the page and returns { ok, anchored, occurrence_used, verified }. verified: true means the posted comment was actually observed; it never returns any document content, so a poisoned document can't smuggle instructions back into your agent. Concurrent calls are serialized behind a mutex, because two keyboard flows in the same window would interleave and corrupt each other.

add_comment ─▶ attach browser ─▶ open doc (?hl=en) ─▶ Ctrl/Cmd+F find_text
             ─▶ check match counter ─(0 matches)─▶ TEXT_NOT_FOUND, nothing posted
             ─▶ Enter×N ─▶ Esc ─▶ Ctrl/Cmd+Alt+M ─▶ type ─▶ Ctrl/Cmd+Enter
             ─▶ verify comment in page ─▶ { ok, occurrence_used, verified }

Limitations

• UI automation is inherently less stable than an API. If Google reworks the editor, this can break until updated. The verified flag tells you whether the comment was actually observed after posting; contributions reporting UI changes are very welcome.
• The logged-in account needs comment access to the target doc.
• find_text must be a single-line fragment (the find bar is one line) and must match the document text exactly.
• An unused session expires after roughly 1–2 weeks; status tells you, login fixes it.
• Calls are serialized, so bulk commenting is sequential by design (typically a few seconds per comment).
• Automating your own Google account through its normal UI is your responsibility under Google's Terms of Service. Use your own account; don't use this for spam.

Security

What the AI agent (and the MCP client) can see. Nothing sensitive. Sign-in happens in a real browser where you type your Google credentials directly to Google — the login step is a terminal CLI, not an MCP tool, so the model is never in that loop and never sees your password, 2FA, cookies, or OAuth tokens. During normal use the add_comment and check_connection tools return structured status only ({ ok, anchored, occurrence_used, verified } / { connected, mode }) and never any document content — so a poisoned document can't smuggle instructions back into the model through this tool. The only things that reach the model's context are what the agent itself supplied (doc, find_text, comment_text) and, occasionally, a local file path inside an error message.

Where the sensitive material actually lives. Your Google session cookies sit in the profile directory (~/.gdocs-comments-mcp/profile), created with 0700 permissions — treat that directory like a password. It stays on disk and is never returned to the model. logout deletes it; you can also revoke server-side via Google device activity. The optional audit log stores hashes only, never content. The one residual risk is ordinary local-machine hygiene: any other process with read access to that directory could reuse the session — that's not an MCP data flow, just standard local security.

Containment. Doc ids are strictly validated and navigation is hard-pinned to docs.google.com — the tool can't be steered to other sites.

FAQ

Can the Google Docs API or Drive API create anchored comments on a specific text range? No. The Google Docs API has no comment endpoints, and the Drive API's comments.create accepts an anchor field that the Docs editor ignores — the comment renders as an unanchored, whole-document comment. This project exists specifically to work around that. See Why not the official APIs?.

How do I add inline / anchored comments to Google Docs programmatically? Use this MCP server, or the same technique it uses: drive the Docs editor UI (find the text, press Ctrl+Alt+M) rather than calling the REST API. How it works documents the full flow.

How do I let an AI agent (Claude, Cursor, Copilot) comment on Google Docs? Add this server to your MCP client (Quickstart) and the agent gets an add_comment tool that posts real, anchored comments — ideal for AI document review, contract/editorial feedback, and automated proofreading workflows.

Do I need a Google Cloud project, OAuth client, or service account? No. Auth is a one-time interactive browser login (gdocs-comments-mcp login) using your normal Google account — no API credentials, no OAuth consent screen, no service-account setup.

Does it work with Google Workspace / shared drives / commenter-only access? Yes, as long as the logged-in account has at least comment access to the document.

Can I run it on a server or in CI? Yes — see Running on a server / datacenter IP. On datacenter IPs you attach to a long-lived logged-in browser over CDP instead of relaunching one.

Contributing

Issues and PRs welcome — especially reports of Docs UI changes that break the keyboard flow (please include your locale and whether verified was false). Plain ESM, no build step: git clone, npm install, node src/cli.js.

License

MIT © Stanisław Herjan

_{Keywords: Google Docs anchored comments · inline comments Google Docs API · add comments to Google Docs programmatically · Google Docs comment API workaround · MCP server Google Docs · Model Context Protocol · Claude / Cursor / Copilot Google Docs integration · AI document review · Playwright Google Docs automation · comment on text range Google Docs.}