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