gdocs — Google Docs review loop for Claude Code

An MCP server that lets Claude Code read a Google Doc and its comment threads, then write corrections back into the same Doc at the same URL.

Built for the loop where Markdown in a repo is the source of truth and Google Docs is only the review surface. It removes the copy-paste round trip: no pasting the draft into Docs, no pasting reviewer comments back into the terminal.

Installed at user scope, so it works in every project.

Requirements

• Node 18+
• The claude CLI
• A Google account, and about 10 minutes in Google Cloud Console

Install

git clone https://github.com/uma-victor1/gdocs-mcp.git
cd gdocs-mcp
./install.sh

That installs dependencies, verifies the server starts, and registers it with Claude Code at user scope. Then do the two credential steps below yourself.

1. Google Cloud, once

1. Create a project: https://console.cloud.google.com/projectcreate
2. Enable Google Docs API and Google Drive API (APIs & Services > Library)
3. OAuth consent screen: user type External is fine for a personal account. Under Audience, add your own address as a test user — skipping this is the most common reason consent fails.
4. Credentials > Create credentials > OAuth client ID > Desktop app > Download JSON
5. Save it as ~/.config/gdocs-mcp/credentials.json

Credentials live outside any repo on purpose, so git add -A can never commit them.

2. Authorise, once

npm run auth

Google warns that the app is unverified. Expected for an app with one user: Advanced > Go to ... (unsafe). The refresh token lands in ~/.config/gdocs-mcp/token.json, mode 0600.

Restart Claude Code, then confirm with claude mcp list.

The 7-day re-auth, and why

While the consent screen sits in Testing, Google expires the refresh token every 7 days. That is documented behaviour for external apps in testing, not a bug, and there is no way around it for this scope set: auth/drive is a restricted scope, and publishing to production with a restricted scope requires a CASA security assessment — not worth it for a one-person tool.

So roughly once a week a tool call will fail with "Authorisation expired". Fix:

npm run auth

Fifteen seconds. If you have a Google Workspace account, you can avoid it entirely: create the Cloud project under that organisation and set the consent screen user type to Internal. Internal apps have no 7-day expiry and no test user list.

Tools

Tool	Effect
find_doc	Search Drive for Docs by title
read_doc	Body as Markdown + comment threads, each with its anchor text
read_comments	Comment threads only — the cheap "any new feedback?" check
replace_text	Exact find-and-replace in place; keeps comment anchors
append_text	Add a styled paragraph at the end (heading level, point size, colour, bold/italic); appends only, keeps anchors
push_markdown	Replace the whole body from a local file; requires confirm: true
reply_comment	Post a reply on a thread
resolve_comment	Resolve a thread with a closing note
create_doc	New Doc from a Markdown file — once per article

All tools accept a Doc URL or a bare fileId.

The comment-anchor tradeoff

Google anchors each comment to a span of text. Rewrite that span and the thread detaches or auto-resolves. So:

• Small fixes → replace_text. Anchors survive; reviewers keep their context.
• Structural rewrites → push_markdown. Faster, but expect thread loss. It reports how many open threads existed beforehand, so the damage is visible rather than silent.
• Adding rather than changing → append_text. It only ever inserts at the end, so no existing span moves and no anchor breaks.
• Reply before you rewrite. reply_comment leaves a record of what changed and why.

Why this and not an off-the-shelf server

An MCP server holding a Docs OAuth token can read and rewrite every document in the account. There is no first-party Google or Anthropic Docs MCP; every published one is a third-party package from an individual publisher. This is ~250 lines on Anthropic's MCP SDK and Google's own client library — small enough to read before you trust it.

Read-only mode

claude mcp remove gdocs -s user
claude mcp add gdocs -s user -e GDOCS_MCP_READONLY=1 -- node "$PWD/server.mjs"

Reads keep working; every write tool refuses. Useful when someone else owns the Doc.

Troubleshooting

Symptom	Fix
"Not authorised yet"	Run npm run auth
Error 403: access_denied, "has not completed the Google verification process"	The signed-in address is not an approved tester. Add it under OAuth consent screen > Audience > Test users, save, retry
"Authorisation expired" after about a week	Expected in Testing mode. Run npm run auth
accessNotConfigured	Enable the Docs API and Drive API on this Cloud project
"no refresh token"	Revoke at https://myaccount.google.com/permissions, re-run npm run auth
Server missing in Claude Code	claude mcp list; re-run ./install.sh; restart Claude Code
Doc exports as plain text	The Doc has content Google can't render as Markdown; content is still returned

Verify the server independently at any time with npm run smoke.

To exercise a single tool without going through Claude Code:

node call.mjs read_comments '{"doc":"https://docs.google.com/document/d/FILEID/edit"}'

Revoking access

https://myaccount.google.com/permissions, then delete ~/.config/gdocs-mcp/token.json.

Layout

server.mjs         the nine tools
google.mjs         auth + Drive/Docs clients; credential paths
auth.mjs           one-time interactive OAuth   (npm run auth)
smoke.mjs          starts the server, lists tools  (npm run smoke)
call.mjs           invoke one tool from the shell, for debugging
install.sh         deps, verify, register at user scope
docs/guide.html    the setup walkthrough as a standalone page

License

MIT. See LICENSE.