io.github.mmedum/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 works inside a document the way a careful colleague does — reads it at the right granularity, edits in place without damaging what surrounds the edit, proposes changes as suggestions, comments on passages, and handles tables, tabs, headers, footnotes and formatting.

Why google-docs-mcp

Existing 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 where the project is enrolled. The reasoning and evidence are in docs/architecture.md.

Reading, searching, creating, exporting, editing with minimal diffs in suggest, direct or comment mode, formatting, reviewing suggestions, comment threads, revision history and diffs, tables, tabs, headers, footers, footnotes, images, chips, named ranges, page and section layout, named styles, gdocs:// resources, large-document performance and agent evals are all in. Every GA member of the Docs API's Request union is emitted; §16 of the architecture says which fields those tools expose and which they deliberately do not.

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.

4. Add scopes (Google Auth Platform → Data Access): .../auth/documents, .../auth/documents.readonly, .../auth/drive, .../auth/drive.readonly.

   All four, though one login never asks for more than two of them: a normal login requests documents and drive, and GDOCS_READ_ONLY=true requests documents.readonly and drive.readonly instead. The consent screen lists what the client may ask for, so it has to cover both, 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.

5. 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.
6. Run:

google-docs-mcp login
google-docs-mcp doctor https://docs.google.com/document/d/<some doc you can open>/edit

The document is optional: doctor on its own checks credentials, scopes and API reachability, and reads the document when given one.

google-docs-mcp status --json prints the same state as one JSON object on stdout, for a script that needs to know whether this server is authorized before starting it. credentials.resolved is the field to branch on, schema_version changes only when a field is removed or its meaning changes, and the account is masked to its domain exactly as the text output masks it. A label in the human output is free to be reworded in any release; the object is not.

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. doctor checks every step and tells you exactly what is missing.

Logging in over SSH

The callback goes to the remote host's loopback address and your browser is local, so the port has to be forwarded. It is drawn at random and appears only in the URL login prints, percent-encoded as 127.0.0.1%3A<port>:

google-docs-mcp login --no-browser

Read the port out of that URL, forward it from a second local terminal, then open the URL in your own browser:

ssh -N -L <port>:127.0.0.1:<port> you@remote-host

If ssh says bind: Address already in use, stop the login with Ctrl-C and start it again to draw a different port. --timeout sets how long login waits; the default is five minutes.

Comments and suggestions

Suggestion mode (mode: suggest), comments pinned to a text range, and accepting or rejecting suggestions use Docs API features Google made generally available on 2026-09-30, rolling out over up to fifteen days. No enrollment is needed. If Google refuses them for a document, reads still work, comments are posted through Drive quoting the text instead of pinned to it, and suggestion mode is refused rather than sent; get_document says which. GDOCS_PREVIEW is deprecated and ignored.

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 writes Word tracked changes under your account's name, which Docs shows as suggestions and Word as tracked changes. mode: direct changes the text. mode: comment and add_comment write Word comments. list_comments lists them; replying to, resolving or deleting one is done in the Docs editor.
• Formatting, tables, images, layout, tabs and reviewing suggestions are refused, saying so: save the file as a Google Doc (File > Save as Google Docs) for those.
• The guard is a Google Doc's: a direct edit that deletes commented text, a suggestion, an image or a footnote reference is refused unless forced.
• Writing while someone has the file open. Each write checks that Docs and the file still agree on every paragraph it reaches, waits and then refuses when they do not, checks again just before the upload, and afterwards checks the file's history: a save that landed in between is put back and the write not applied. An editor that has the file open reloads it. The write then waits until Docs has read the new revision.

Connect a client

Claude Code:

claude mcp add --transport stdio google-docs -- google-docs-mcp

Claude Desktop (claude_desktop_config.json) or Cursor (mcp.json):

{
  "mcpServers": {
    "google-docs": {
      "command": "/absolute/path/to/google-docs-mcp",
      "env": { "GDOCS_LOG_LEVEL": "info" }
    }
  }
}

Claude Desktop rewrites claude_desktop_config.json from its own state while it runs, dropping edits made behind its back: quit it fully, then edit, then start it. It also loads tool definitions lazily, so give it a moment before expecting the tools in a chat.

Claude Desktop can instead open the .mcpb bundle from a release, with no config file to edit. It asks for the same settings: the OAuth client JSON, which may be left empty to use the one login recorded, the profile, read-only, the default write mode, deleting comments and tabs (enable_destructive) and the export folder (export_dir). Deleting stays off unless you turn it on, and binary exports stay off until you pick a folder. This server asks nobody before a call. Claude Desktop approves each tool, with Allow once or Always allow, and a tool you always allow then runs unasked, so leave enable_destructive off unless you need its tools. The bundle covers macOS and Linux on both architectures, and Windows with its amd64 binary, which Windows on arm64 runs under emulation. It does not log you in: install the binary as well, run google-docs-mcp login once, and the bundle picks up the same credentials.

All settings are environment variables; see docs/configuration.md. Nothing needs to be set for the defaults.

Tools

Two more tools register only with GDOCS_ENABLE_DESTRUCTIVE=true: delete_comment (a thread or one reply) and delete_tab (a tab with its content and child tabs). Both carry the destructive annotation, and each call must repeat its target in confirm_comment_id or confirm_tab. delete_comment also takes text_start, how the text it deletes begins as list_comments shows it, so your client's prompt shows which comment goes; the server reads the comment and refuses [stale] when it differs.

Documents are identified by id, any docs.google.com URL, or a Markdown file's drive.google.com/file/d/… URL.

Resources

Clients that attach context as MCP resources can read a document without a tool call. Each is markdown with no handles, suggestions or comments; the read tools are for scoped, budgeted reads.

• gdocs://<id> — every tab's body, cut at 400000 characters with a note saying where read_document can continue.
• gdocs://<id>/outline — the heading tree get_outline returns.
• gdocs://<id>/tabs/<tab> — one tab's body; tab is an id, title or number.

How edits are addressed

The model never sees index numbers. A target is exact text quoted from a read (curly quotes, dashes and spacing are normalized; it must occur once, or occurrence / within disambiguates), a whole section by its stable heading_id, a block by handle (p12, valid for the revision it came from and re-checked on use), a table cell, or a named range, which is the one anchor that outlives an edit: Google moves it with the text it covers, so create_named_range now and target: {named_range: …} in a later call reach the same passage. New content is written as markdown. A replace is applied as the smallest diff between the old and new text, so untouched words keep their formatting and anchored comments.

Tables are named by handle (tbl1) and cells as r2c3; a table that gets a data grid is inserted empty and filled in a second batch once it exists. Table ops read in order: once one changes the grid, the ops after it on that table are applied in a batch of their own, so their row, column and cell numbers mean the grid as it is by then. Old revisions are read and diffed through Google's export, so they have no handles.

Safety

• Read tools are annotated read-only. Write tools take a mode chosen by the person: suggest (tracked change), direct, or comment (the proposal is posted as a comment and nothing is edited). Every write is guarded by the revision it was planned against; a concurrent edit is re-planned once, then refused.
• Direct edits never delete a range that holds a comment anchor, a pending suggestion, an image or a footnote unless explicitly forced.
• Destructive tools (deleting comments or tabs) are not registered unless GDOCS_ENABLE_DESTRUCTIVE=true. GDOCS_READ_ONLY=true registers only read tools and requests read-only scopes.

• Your MCP client approves each call; the server asks you nothing. claude.ai and Codex prompt for the two deletes, which are marked destructive. VS Code prompts for every tool that is not read-only: every write, and export_document, which writes a local file. In Claude Code, list the calls you want to approve one by one under permissions.ask in your settings, with the name you gave the server in place of google-docs. For example, the deletes, reviewing other people's suggestions, and writing a Markdown file back:

  {
    "permissions": {
      "ask": [
        "mcp__google-docs__delete_comment", "mcp__google-docs__delete_tab",
        "mcp__google-docs__review_suggestion", "mcp__google-docs__write_markdown_file"
      ]
    }
  }

  GDOCS_REQUIRE_PROMPT is gone: set to anything but false, the server will not start. Leave GDOCS_ENABLE_DESTRUCTIVE off for a client that runs with nobody watching.

• The server talks only to Google (googleapis.com, and docs.google.com for the revision export links Google's API returns). No telemetry. Logs (stderr) never contain document text.
• Refresh tokens live in the OS keyring; logout revokes and deletes.

How it works

MCP client ──stdio──► google-docs-mcp
                       ├── tools     one handler per tool; shapes the reply
                       ├── service   orchestration and scope resolution
                       ├── plan      write planning and all the index math
                       ├── doc       model, handles, sections
                       ├── render    markdown, text, outline
                       ├── gapi      raw REST client for Docs and Drive
                       └── auth      refresh token → access token

Index math never leaves the server: the model addresses content by exact text, heading_id or handle, and internal/plan turns that into the UTF-16 offsets the Docs API wants. The wire types in internal/gdocs are this project's own, held to Google's published discovery document by a gate, rather than the generated client.

Getting help

google-docs-mcp doctor checks credentials, scopes and API reachability and names what is missing; most first-run trouble is an API that was never enabled or a consent screen without you on it. If that does not explain it, open an issue — the bug form asks for the doctor output and the version.

Never paste a document id or URL, document content, a client_secret.json or a token into an issue; describe the shape of the document instead. Security problems go through SECURITY.md, privately.

Versioning

From v1.0.0, semver as you would expect: a tool removed or renamed, an argument that becomes required, or a change to what a tool returns is a major version. New tools and new optional arguments are minor. The schema diff in CI is what enforces it, and it runs on every pull request — the tool surface cannot change without the diff naming it.

The one exclusion, stated so it is a decision rather than a surprise: the exact prose of a tool's text output, which is written for a model to read and will be reworded when a model reads it badly. The structuredContent a tool returns is covered; the sentence wrapped around it is not.

Each release's notes are the matching section of CHANGELOG.md; a change needing you to act — a new scope, another login, a different command in your client config — is marked Breaking: there.

Development

make build     # the binary
make test      # race detector, coverage floor
make check     # everything CI runs

make check is the definition of done: formatting, go vet under every build tag, golangci-lint, race tests with a per-package coverage floor, govulncheck, a license check, a secret scan, an API-coverage gate and an API-fields gate that fail when a Google API method or field has no verdict on it, a schema diff against the released tool surface, a stdio smoke test, and a staleness gate that fails when this README, the docs or the changelog drift from the code.

Test fixtures are synthetic. Never add content, ids or URLs from real documents. make bench measures the large-document paths; go test -tags=evals ./internal/evals runs the agent evals against your own account (see the package comment).

Documentation

• docs/architecture.md — the design, the request flow, the evidence log behind every convention, and the decisions a contributor should not undo.
• docs/configuration.md — every environment variable and flag.
• docs/security.md — the threat model: what reaches a log, what doctor prints, what the drivers write. Each claim is held by a test.

Contributing

Questions and bugs go in issues; pull requests are welcome. CONTRIBUTING.md covers the branch and review flow, and make check is what has to pass.

Security

SECURITY.md says what is in scope and how to report a vulnerability privately. Do not open a public issue for one.

Code of conduct

CODE_OF_CONDUCT.md — Contributor Covenant 3.0.

License

Apache-2.0 — see LICENSE.