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/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.

Optional: Developer Preview

Suggestion mode (mode: suggest), comments anchored to a text range, and accepting or rejecting suggestions use Docs API features that are in the Google Workspace Developer Preview Program. Apply with the form on that page, giving your Cloud project id. Once enabled for your project, set GDOCS_PREVIEW=true. The program terms allow use inside your own organization; do not offer a preview-enabled deployment to people outside it.

These features sit outside the version promise below. They are the one part of this server built on an API Google may change or withdraw while it is in preview, and a change there is not something this project can absorb without changing behavior. Everything reachable with GDOCS_PREVIEW unset follows semver as stated; the preview-gated features follow Google's preview program, and if it moves, they move.

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.

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

Tools