google-drive-mcp

# google-drive-mcp

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

A [Model Context Protocol](https://modelcontextprotocol.io) server for
Google Drive, written in Go: find files and know where they live and who
can see them, organise folders, move and copy, get content in and out,
share without widening access by accident, follow what changed, and
manage shared drives. It stops at the file boundary; what happens inside
a Google Doc, Sheet or Slides deck is out of scope and belongs to servers
built on the Docs, Sheets and Slides APIs.

Single binary, stdio, one Google account per profile. You run it against
a Google Cloud project you own, so nothing about this repository is tied
to any particular organisation or account.

**Status: v1.0.2, phase 6 of the plan in
[docs/architecture.md](docs/architecture.md).** The tools below work, and
every one of them is verified against a real Google Workspace account as
well as against the in-memory Drive the tests use — the five that remove
something for good included, which run inside a shared drive the live
driver creates and destroys again. Four paths are not: handing over
ownership of a file, opening a link-shared file that needs its resource
key, a share an organisation's policy refuses, and applying a label. Each
needs a second Google account or an administrator to exercise, and
[docs/architecture.md](docs/architecture.md) §17a says what stands in for
each of them.

## What it does today

| Tool | What it does |
|---|---|
| `get_account` | Who is signed in, storage used, whether this account has shared drives, and which of this server's tools are registered |
| `get_file` | Everything about one file: kind, location, link, size, owner, who can see it, and what you may do with it |
| `list_folder` | One page of a folder's contents, or a budgeted tree of everything below it |
| `search_files` | Find files across My Drive, files shared with you, and every shared drive |
| `read_file` | The text of a file: a Doc as markdown, a Sheet as csv, a log or source file as itself, windowed with a continuation |
| `download_file` | Write a file to the local directory, converting a Google document on the way out, checksum-verified |
| `create_file` | A new empty Google file, or one written from text you have here, with optional conversion |
| `upload_file` | Send a local file, in one request or in chunks that survive a dropped connection |
| `update_content` | Replace what is inside a file, keeping its id, its place and everything that points at it |
| `create_folder` | A new folder, refusing a duplicate name unless you allow it |
| `update_file` | Rename, describe, star, colour, set properties, or turn off copying and re-sharing |
| `move_file` | Move an item to another folder or shared drive, with a dry run |
| `copy_file` | Copy a file, optionally asking Google to import it as a Doc, which reads the text out of a PDF or a scan; with `recursive`, a whole folder |
| `create_shortcut` | A pointer to one item from another folder |
| `trash_file` | Move an item to the trash, which is reversible |
| `restore_file` | Take an item out of the trash, and say where it went |
| `list_permissions` | Who can see an item, with the role, the expiry, and where each grant came from |
| `share_file` | Grant or change access, with who can see it before and after |
| `unshare_file` | Take access away, or kill the link that let anybody open it |
| `list_drives` | The shared drives this account can see, with what it may do in each |
| `manage_drive` | Create, rename, hide, unhide or restrict a shared drive |
| `list_revisions` | A file's version history, with Google's own caveat about what it leaves out |
| `manage_revision` | Pin a version so Drive keeps it, or unpin it again |
| `list_changes` | What has changed since a point in time, with the token for next time |
| `list_comments` | The threads on a file, with their replies and whether each is still open |
| `add_comment` | Start a thread on any file, Google document or not |
| `reply_comment` | Answer a thread, resolve it, reopen it, or edit wording already in it |
| `list_access_requests` | Who has asked to be let into a file, and what they asked for |
| `resolve_access_request` | Accept or deny one, with who could see the file before and after |
| `list_approvals` | The reviews on a file: who asked, who has to answer, and whether it is waiting on you |
| `manage_approval` | Ask people to review a file, answer one, withdraw it, comment on it, or change who is asked |

Three more are registered only when the deployer turns their feature on,
because each needs a scope the consent screen would otherwise not carry:
`list_labels` and `manage_labels` with `GDRIVE_LABELS=true`, and
`list_activity` with `GDRIVE_ACTIVITY=true`.

| Tool | What it does |
|---|---|
| `list_labels` | The Workspace labels this account can use, with each field and the values it takes |
| `manage_labels` | Put a label on a file, set or clear one of its fields, or take it off |
| `list_activity` | What happened to a file, or to everything in a folder, and when |

Five more are registered only with `GDRIVE_ENABLE_DESTRUCTIVE=true`, and
each of those also needs `confirm: true` on the call itself:
`delete_file`, `empty_trash`, `delete_drive`, `delete_revision` and
`delete_comment`.

Three of the reads are also **resources**, for a client that attaches
them rather than calling a tool: `gdrive://<id>` is the file's text,
`gdrive://<id>/meta` is the description, and `gdrive://<id>/children` is
a folder's first page. A reference with a slash in it — a path, a URL —
has to be percent-encoded there, so pass an id.

Five things it does differently from the alternatives:

- **Shared drives work from the first call.** Every request carries
  `supportsAllDrives`, listings include items from all drives, and an
  incomplete search says so instead of quietly returning less.
- **Ids are the contract.** A name or path matching more than one item
  comes back as `[ambiguous]` with every candidate listed. Nothing takes
  the first match.
- **Location is always shown.** Names are not unique in Drive, so every
  result says which folder, and which drive, a file sits in.
- **Files go one place only.** Downloads land in `GDRIVE_LOCAL_DIR` and
  uploads are read from it; unset, there is no file transfer at all. A
  path outside it is refused, symlinks included.
- **Sharing shows its work.** Every grant or revocation reports who could
  see the file before and who can see it after. A public link needs
  `allow_anyone: true` and an ownership transfer needs
  `transfer_ownership: true`, on the call itself. No notification mail
  goes out unless you ask for it, which is the opposite of the API's own
  default.

## Install

```
go install github.com/mmedum/google-drive-mcp/cmd/google-drive-mcp@latest
```

That puts the binary in Go's bin directory, which is often not on your
`PATH`. If the next command says `command not found`, either use the full
path or add the directory once:

```
"$(go env GOPATH)/bin/google-drive-mcp" --version    # check it landed
export PATH="$(go env GOPATH)/bin:$PATH"             # or add it to your shell profile
```

Or take a signed archive from the
[latest release](https://github.com/mmedum/google-drive-mcp/releases/latest)
— Linux, macOS and Windows, on amd64 and arm64 — and put the binary on
your `PATH`. Every archive carries the binary, `LICENSE` and this README.
Nothing about a release has to be taken on trust:

```bash
# --ignore-missing, because checksums.txt covers every archive and you
# will have downloaded one of them.
sha256sum -c checksums.txt --ignore-missing

# checksums.txt is signed with a keyless Sigstore certificate tied to the
# release workflow's identity; the bundle carries the signature and the
# certificate together.
cosign verify-blob checksums.txt --bundle checksums.txt.bundle \
  --certificate-identity-regexp '^https://github.com/mmedum/google-drive-mcp' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# And each archive carries build provenance naming the workflow and tag
# that produced it.
gh attestation verify google-drive-mcp_*.tar.gz --repo mmedum/google-drive-mcp
```

Every archive also ships an SBOM, so you can see what is inside a binary
you did not build.

### Claude Desktop

Every release also carries a `.mcpb` bundle. Open it and Claude Desktop
installs the server and asks for your OAuth client JSON — no config file
to edit. It covers macOS, Windows and Linux on both architectures each:
macOS through a universal binary, Windows through amd64, and Linux
through a small launcher that picks the right binary at start, because a
bundle manifest names a command per platform and has no key for the
architecture. Its SHA-256 is in the same signed `checksums.txt`.

The bundle does not log you in. Install the binary as well, run
`google-drive-mcp login` once, and the bundle picks up the same
credentials. Claude Code does not install `.mcpb` files, so it uses the
command below.

## Set up Google, once per person

You need your own Google Cloud project and your own OAuth client. This
takes about five minutes, and `google-drive-mcp doctor` tells you which
step you missed.

1. **Create a project** at [console.cloud.google.com](https://console.cloud.google.com/projectcreate).
2. **Enable the Google Drive API** for it, under *APIs & Services →
   Library*.
3. **Configure the OAuth consent screen.**
   - On a Google Workspace acc