google-docs-mcp

# google-docs-mcp

[![CI](https://github.com/mmedum/google-docs-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mmedum/google-docs-mcp/actions/workflows/ci.yml)
[![Latest release](https://img.shields.io/github/v/release/mmedum/google-docs-mcp?sort=semver)](https://github.com/mmedum/google-docs-mcp/releases/latest)
[![Go Reference](https://pkg.go.dev/badge/github.com/mmedum/google-docs-mcp.svg)](https://pkg.go.dev/github.com/mmedum/google-docs-mcp)
[![License: Apache 2.0](https://img.shields.io/github/license/mmedum/google-docs-mcp)](./LICENSE)

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](https://modelcontextprotocol.io)
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`](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

```bash
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](https://github.com/mmedum/google-docs-mcp/releases/latest)
— Linux, macOS and Windows, on amd64 and arm64 — and verify it before you
run it:

```bash
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 organisation.
     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:

```bash
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
authorised 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>`:

```bash
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:

```bash
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](https://developers.google.com/workspace/preview).
Apply with the form on that page, giving your Cloud project id. Once
enabled for your project, set `GDOCS_PREVIEW=true`. The programme terms
allow use inside your own organisation; 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 behaviour. Everything reachable with
`GDOCS_PREVIEW` unset follows semver as stated; the preview-gated
features follow Google's preview programme, and if it moves, they move.

## Connect a client

Claude Code:

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

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

```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`](docs/configuration.md). Nothing needs to be set
for the defaults.

## Tools

| Tool | What it does |
|---|---|
| `get_document` | Title, tabs, revision id, owner, last change, counts, and this server's capabilities (available write modes, default). Per tab it also reports the page setup, the floating objects, the named ranges and the named style definitions its paragraphs carry — everything a read of the text cannot show. Cheap; call it first. |
| `get_outline` | Heading tree per tab with stable `heading_id`s, block handles, and section sizes. |
| `read_document` | Scoped, budgeted read as markdown, plain text, or raw Docs JSON. Scope by `heading_id`, heading text, handle range, tab, or header/footer/footnote. Block handles come with the text unless `with_handles` is false; options add styles, pending suggestions as `{++inserted++}` / `{--deleted--}` / `{==restyled==}`, and comment markers `{>>c:id<<}`. |
| `find_in_document` | Text or regex search returning handles, offsets and context. |
| `search_documents` | Locate documents by title or content, owner, or modification date. |
| `export_document` | Google's own md, txt, html inline; pdf, docx, odt, rtf, epub as files under `GDOCS_EXPORT_DIR`. |
| `create_document` | New document, optionally with markdown content. |
| `edit_document` | Atomic batch of `insert`, `append`, `replace` (minimal diff), `delete`, `replace_all`, `insert_break`, `insert_