Gdocs Comments MCP

gdocs-comments-mcp

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

= 18">

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.

Manual setup

1. Log in once — opens a browser window; the Google session is saved to a local profile (~/.gdocs-comments-mcp/profile):

npx -y gdocs-comments-mcp login

2. Add the server to your MCP client:

# Claude Code

claude mcp add gdocs-comments -- npx -y gdocs-comments-mcp

Other MCP clients — after login, add the config for your client:

Claude Desktop / Cowork

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{

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

</details>

Project-level .mcp.json (shared with your team via git)

Create .mcp.json in the project root — Claude Code, Cowork, and most MCP clients pick it up:

{

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

Note: every user of the project still runs npx gdocs-comments-mcp login once on their own machine — sessions are personal and never shared through git.

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{

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

</details>

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{

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

</details>

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 C