Gdocs MCP

@dasasian/gdocs-mcp

An MCP server that lets an AI agent (like Claude Code) treat a Google Doc like a local file — read it, edit it by content, review and resolve suggestions, manage comments, and work across tabs and multiple Google accounts.

Status: beta. The tool surface is complete and every change is verified against the live API, not just unit tests.

Why this exists

Most Google Docs MCP servers treat a doc as flat text. This one fills the gap nobody else does:

• Suggestions you can read and act on. list_suggestions shows each pending tracked change with Docs' own summary, the change in its sentence (Pay within [30→45] days), its author and time; apply_suggestions accepts or rejects each one on its own, as the check and the cross do in Docs. read_doc can render them inline as / .
• File-like editing. edit_doc matches a unique snippet of text (like a local Edit) and rewrites it — indices are never exposed.
• Comments on their text. Read threads (author, time, the text each is on, replies, resolved status), reply, resolve, and add a comment on the text you quote, which stays on that text as it moves.
• Tabs as sub-files. A doc is a folder of tabs: drive ls lists them, drive mv renames, reorders and nests them.
• Multiple accounts. Authorize several Google accounts; pick a default per project.

What you can ask for

You don't call tools. You ask in plain language and the agent drives them.

Fill a template without rebuilding it

*"Copy the Proposal Template into /Clients/Acme, name it 'Acme Q3 Proposal', then fill in the client name, the dates, and the pricing table."*

The copy keeps the letterhead, the logo at its exact size, the fonts and the page setup — everything a markdown round-trip cannot rebuild. Then only the words that change are edited. The alternative is retyping a document you already have.

A whole review pass in one instruction

*"Show me the pending suggestions as a diff, accept the typo fixes, reject anything that changes meaning, then reply to the open comments and resolve the ones that are settled."*

Four tools, one sentence, and the judgement in the middle is the part you wanted help with. Most Docs integrations cannot see tracked changes at all, let alone act on them safely.

More: publishing a folder of markdown as a Drive tree, auditing many docs for style drift, pulling a doc back into your repo with its images → [docs/recipes.md](docs/recipes.md).

Install

npm install -g @dasasian/gdocs-mcp

Or from source:

git clone https://github.com/dasasian/gdocs-mcp && cd gdocs-mcp

npm install && npm run build npm link # makes gdocs-mcp available globally, same as the published package

Then follow the setup below exactly as an installed user would. (npm link symlinks the gdocs-mcp binary to your build; see CONTRIBUTING.md for the dev workflow.)

Setup

You need a Google Cloud OAuth client (one-time). Each user creates their own — this keeps your credentials yours and avoids Google app-verification for the restricted Drive scope.

1. Create a project + enable APIs (or use the setup guide):

   gcloud projects create my-gdocs-mcp

gcloud config set project my-gdocs-mcp gcloud services enable docs.googleapis.com drive.googleapis.com

2. **OAuth consent screen** (Cloud Console → APIs & Services → OAuth consent screen): User type **External**, add yourself as a **Test user**. For long-lived tokens, set publishing status to **In production** (avoids the 7-day refresh-token expiry).

1. OAuth client → Create credentials → OAuth client ID → Desktop app. Download the JSON and save it as ~/.config/gdocs-mcp/client_secret.json.
2. Authorize an account (opens a browser):

   gdocs-mcp add-account

Repeat for each Google account you want to use.

Configure your MCP client

In a project's .mcp.json (Claude Code) or equivalent:

{

"mcpServers": { "gdocs": { "command": "gdocs-mcp", "env": { "GDOCS_DEFAULT_ACCOUNT": "you@example.com" } } } }

GDOCS_DEFAULT_ACCOUNT sets which authorized account this project uses by default — so a work project and a personal project can point at different accounts without re-authorizing. Any tool call can override it with an account argument.

Prefer it available in every project? Register once at user scope: claude mcp add gdocs -s user -e GDOCS_DEFAULT_ACCOUNT=you@example.com -- gdocs-mcp. Then a project can pin its own defaults with a .gdocs-mcp.json — the account, and a default folder for new docs:

{ "account": "work@company.com", "folder": "https://drive.google.com/drive/folders/…" }

write_doc creates only from a path (/Reports/Q3 Report). Given a bare name (Q3 Report) it creates nothing: it refuses, tells the agent to tell you the doc will go in the default folder, and hands back the full path to call. A new doc at the top of My Drive (/Q3 Report) is refused once the same way, and the identical call repeated goes through if you want it there. The default folder's path is also in write_doc's description, read when the server starts. With no default it says to name a folder (~/Q3 Report). See docs/setup.md for the full resolution order.

You don't have to edit that file by hand — just tell the agent *"make damithsc@gmail.com my default account for this project"* or *"make my Manuscripts folder the default here,"* and it writes the .gdocs-mcp.json for you via set_project_default (searching for the folder by name if needed).

Tools

The table below is the reference. For what to actually *ask for*, see What you can ask for above, or the full set in [docs/recipes.md](docs/recipes.md).

| write_doc | Write like the local Write: a path that names nothing is created — a doc in a folder (/Work/Contract), a tab in a doc (/Work/Contract/Notes), a child tab (/Work/Contract/Part 2/Ch.4) — and never asks. A path that names something is replaced, and the first call is refused with a loss summary: paragraphs, comments, suggestions, tab stops, links to bookmarks, page-number fields, section breaks, a table of contents, column breaks, equations, dates in a format the API can only read and link chips to anything but a Drive file, plus a confirmLoss string. Footnotes, pers