Google Docs MCP

google-docs-mcp

Google Docs as MCP tools. Read, edit, suggest and comment on documents from Claude or any MCP client.

A single Go binary that speaks Model Context Protocol over stdio. It runs as a subprocess of your client, on your own machine, against your own Google account. There is no server to host, no shared deployment and no service account: you create a Google OAuth client, log in once, and the refresh token stays in your OS keyring.

It is for a person with a Google account who wants an assistant to work inside their documents the way a careful colleague does. It reads a document at the right granularity, edits in place without damaging what surrounds the edit, proposes changes as suggestions, and comments on passages. It handles tables, tabs, headers, footnotes and formatting, and Markdown and Word files Docs opens in Drive. Folders, sharing and moving files belong to a Drive server such as google-drive-mcp.

Goals and non-goals

Goals:

• Nothing in a document is destroyed by accident. A replace changes only the words that differ. A direct edit that would delete a comment anchor, a suggestion, an image or a footnote is refused unless forced, and suggest and comment modes delete nothing.
• Edits land where they were meant to. The model addresses content by exact text, heading id, block handle or named range, never by an index. Every write is checked against the revision it was planned on.
• You decide how a change lands. Suggest, direct or comment, with a default you set; the server never swaps one for another.
• Results say what happened. A write reports what it touched and the new revision. A write that may have landed says so rather than being sent twice.
• Your documents stay yours. Every call runs as the signed-in account, only to Google's hosts, with no telemetry. Logs never carry a document id, title or text.

Non-goals:

• Folders, moves, sharing, trash and copies. The scope is one document and everything inside it, its history included.
• A hosted service. It speaks stdio only.
• Round-tripping a document through Markdown. Markdown is for new content. What the Docs API cannot express is refused, naming the construct, rather than approximated.
• What the Docs API cannot do: insert a chart or a table of contents, write an equation or a drawing, read an old revision's structure rather than its export, or fetch an image from a private address.
• Asking you before a call. Your client approves each call; the server asks nothing.

Why google-docs-mcp

Other servers hand the model raw UTF-16 indices, convert Markdown in ways that silently corrupt documents, and anchor comments through the Drive API, where they never render inline. This server keeps index math on the server, addresses content by exact text and stable heading ids, edits by minimal diff, refuses to overwrite anchored content, and uses the Docs API's suggestion mode and pinned comments. Every GA request of the Docs API is emitted. The reasoning, one decision at a time, is in docs/architecture.md.

Install

go install github.com/mmedum/google-docs-mcp/v3/cmd/google-docs-mcp@latest

That puts google-docs-mcp in $(go env GOPATH)/bin, which is the path to give your MCP client. Or take a signed archive from the latest release — Linux, macOS and Windows, on amd64 and arm64 — and verify it before you run it:

tar xzf google-docs-mcp_*_linux_amd64.tar.gz

sha256sum -c checksums.txt --ignore-missing

The checksum file is signed with a keyless Sigstore certificate tied to

the release workflow's identity. The bundle carries both.

cosign verify-blob checksums.txt \ --bundle checksums.txt.bundle \ --certificate-identity-regexp 'https://github\.com/mmedum/google-docs-mcp/' \ --certificate-oidc-issuer https://token.actions.githubusercontent.com

And the archive itself carries build provenance.

gh attestation verify google-docs-mcp_*_linux_amd64.tar.gz --repo mmedum/google-docs-mcp

Every archive also ships an SBOM (.sbom.json), so you can see what is inside a binary you did not build. go install needs none of this: the module proxy and sum.golang.org verify the source before it is built. google-docs-mcp --version reports the release it came from either way.

Set up Google

Every deployer uses their own Google Cloud project and OAuth client. There is no shared app and nothing to verify with Google.

1. Create or pick a Google Cloud project.
2. Enable the Google Docs API and the Google Drive API (APIs & Services → Library).
3. Configure the OAuth consent screen (Google Auth Platform → Audience):

• Internal if your account is in a Google Workspace organization. Tokens then never expire.
• External with publishing status Testing for a consumer account. Add yourself as a test user. Google expires refresh tokens for such apps after 7 days, so you will run login weekly.

1. On an External app, add the scopes (Google Auth Platform → Data Access): .../auth/documents, .../auth/documents.readonly, .../auth/drive, .../auth/drive.readonly. Google asks for the list only from apps used by people outside your Workspace organization, so an Internal app can skip this step. Listing them there anyway does no harm.

One login asks for one pair of them: a normal login requests documents and drive, and GDOCS_READ_ONLY=true requests documents.readonly and drive.readonly instead. An External app's consent screen lists what the client may ask for, so it has to cover both pairs, and a scope it has not been given is refused at the moment somebody first tries read-only mode. Google grants only what is requested, so listing the read-only pair costs a normal login nothing.

1. Create an OAuth client (Google Auth Platform → Clients) of type Desktop app, download its JSON, and store it as ~/.config/google-docs-mcp/client_secret.json (Linux; the google-docs-mcp folder under your OS config directory elsewhere). Keep it out of any repository.
2. Run:

google-docs-mcp login

google-docs-mcp doctor https://docs.google.com/document/d/ /edit

login opens a browser, completes Google's desktop OAuth flow on a loopback port, and stores the refresh token in your OS keyring (Secret Service, Keychain or Credential Manager), falling back to a 0600 file with a warning when no keyring is available. Over SSH, the callback port has to be forwarded; troubleshooting says how.

doctor checks the credentials, the granted scopes and the APIs, and reads the document when given one. When a check fails, docs/troubleshooting.md says what it means.

Markdown files

Docs opens a Markdown file stored in Drive (.md, typed text/markdown) and edits it in place, leaving it a Markdown file. The Docs API reads such a file but refuses every write to it, and nothing writes through an open editor's session: the only write is an upload of the whole file, and an upload makes an open editor reload. So there are two ways to work on one.

Together, live: a working copy. create_document with from_file makes a Google Doc from the file. You and Claude work in it as in any Google Doc: edits merge with your typing, suggestion mode shows tracked changes, comments sit on their passage. write_markdown_file then writes what changed in the copy back into the file, block by block. The rest of the file keeps its own Markdown, its front matter and the comments Docs keeps in it. A change to a block that was also changed in the file since the copy was made is a conflict, refused unless force keeps the file's version of those.

Directly, on the file. get_document says kind: markdown_file, reads return the file's own Markdown, and edits are minimal changes to that text, uploaded once per call:

• Targets are exact text, heading_id (a slug such as next-steps, from get_outline) or heading. Lines (L12) stand where a Google Doc has handles, and a long read continues from one.
• edit_document takes insert, append, replace, delete and replace_all, with content written as given. Formatting, tables, objects, layout and tabs are refused: write them as Markdown.
• mode: direct changes the text. mode: comment and add_comment write a comment into the file under your account's name, the way the editor writes its own; the editor shows it, marked "From imported document", and keeps it when you save. Its id changes each time the file is written, until someone saves the file in the editor. reply_comment replies the same way. Resolving cannot be done through the file (written into it, a resolve makes Google fail to read the file), so you resolve in the editor. A Markdown file takes no suggestions.
• The comments Docs keeps in the file are left out of reads, never touched by an edit, and listed by list_comments along with comments made through Drive's API. Content that holds comment markup is refused.
• The guard refuses a direct edit that changes commented text, an image or a footnote reference unless forced, as in a Google Doc.
• Writing while someone has the file open. Drive has no way to make an upload conditional, and an open editor holds work the file does not show yet. Before writing, the server compares the editor's live session with the file: if a comment, reply or resolve has not reached the file, it waits a moment, then refuses, force or not: that work is in no revision yet. Just before the upload it checks again. After it, it checks the file's history: if someone's save landed in between, the save is kept and the change made again on top of it.
• When a person saves the file in the Docs editor, Docs rewrites all of it in its own Markdown style and turns front matter into a heading. A read warns about front matter; list_revisions and read_document with revision reach the earlier text.
• search_documents finds Markdown files with kind: markdown_file or any; its default is Google Docs only. create_document with kind: markdown_file makes a new one.

Word files

Docs opens a Word file stored in Drive (.docx) and edits it in place, leaving it a Word file. The Docs API reads one, its tracked changes as suggestions and its comments as comments, and refuses every write to it. So this server writes the file itself: get_document says kind: word_file, reads work as on a Google Doc, handles included, and an edit is made in the file's XML and uploaded whole through Drive.

• edit_document takes insert, append, replace, delete and replace_all on the body's text, addressed as on a Google Doc; replace_all leaves a match in a header, footer or footnote, with a warning. Text replaced inside a paragraph changes by its minimal difference and keeps its look; content of several paragraphs goes between paragraphs or replaces whole ones. Headings take the file's own heading styles, and lists continue the list they are placed against, at a level list_level can set.
• mode: suggest writ