Google Drive

google-drive-mcp

[CI] [Latest release] [Go Reference] [License: Apache 2.0]

Google Drive as MCP tools. Find, organize, share and move files, and follow what changed. One Go binary that speaks Model Context Protocol over stdio, signed in as you, with your own OAuth client and the refresh token in your OS keyring.

It is for a person with a Google account who wants an assistant to work with the files they can already reach in Drive, as them. It works at the file boundary: where a file sits, who can see it, folders, moves and copies, content in and out, sharing, shared drives, revisions, comments and what changed. What is inside a Doc, Sheet or Slides deck belongs to servers built on those APIs.

Goals and non-goals

Goals:

• Access never widens by accident. Google's sharing policy decides what may be shared. share_file grants named people and groups inside your organization, and every wider share is a tool of its own, off by default. A move or a copy never reaches past the organization. Every share shows who could see the item before and after, and sends no mail unless asked.
• Nothing is destroyed without a way back unless you turn it on. Trash and restore are the default. The permanent deletes are not registered by default, and each needs confirm: true.
• The model never guesses which file. Ids are the contract: a name or path matching more than one item comes back as [ambiguous] with every candidate, and every result says which folder and drive a file sits in.
• Shared drives work from the first call. Every request reaches them, and an incomplete search says so instead of quietly returning less.
• Results say what Drive answered, never what the request asked for. Where Drive's reads lag its own writes, the result says so.
• Files move through one directory. Downloads land in GDRIVE_LOCAL_DIR and uploads are read from it; unset, there is no file transfer. Transfers stream in chunks and are checked against Drive's md5.
• Act as you, and log nothing about your files. Every call runs as the signed-in account, only to Google's hosts, with no telemetry. Logs never carry file names, paths, addresses, queries or content.

Non-goals:

• What is inside a Doc, Sheet or Slides deck. It reads them through Google's export and says so. A comment made here sits on the file rather than on a place in it.
• Sync or push. Watch channels need a public HTTPS endpoint; list_changes reads the changes feed with a token instead.
• Domain administration. It acts as the signed-in person and sees what they see.
• Publishing a revision to the web, which is exposure with no control over who sees it.
• Client-side encryption, Apps Script, the Drive UI integration and the app data folder.
• A hosted service. It speaks stdio only.
• Asking you before a call. Your client approves each call; the server asks nothing.

Tools

Drive has no substring search. In search_files, each word of name has to begin some word of the file's name, in any order, so "Bud" finds "Budget 2026" and "udget" finds nothing. Search text by whole words.

These are registered only when the deployer turns their feature on, because each needs another Google API and a scope login would otherwise not ask for: list_labels and manage_labels with GDRIVE_LABELS=true, and list_activity with GDRIVE_ACTIVITY=true.

More are registered only with GDRIVE_ENABLE_DESTRUCTIVE=true, and each of those also needs confirm: true on the call itself. These remove something for good: delete_file, empty_trash, delete_drive, delete_revision and delete_comment. These reach past your organization: share_by_link opens a file to anyone with the link or a whole domain, share_outside_organization grants someone outside it, transfer_ownership hands a file to a new owner, and lift_drive_restriction lets a shared drive's content be shared outside the organization. The tools that reach past it also take the name of what they open up, file_name or drive_name, so the call your client shows you for approval says which file or drive it is; a name that is not the item's is refused.

Some 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, such as a path or a URL, has to be percent-encoded there, so pass an id.

The live driver runs every tool against a real Google Workspace account as well as the in-memory Drive the tests use, the permanent deletes included, inside a shared drive it creates and deletes. The paths that need a second account or an administrator have not run live: handing over ownership, opening a link-shared file that needs its resource key, a share an organization's policy refuses, and applying a label. Each is tested against the in-memory Drive, and the driver has a mode for each but the resource key: -transfer, -blocked and -labels.

Install

go install github.com/mmedum/google-drive-mcp/v3/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 landedexport PATH="$(go env GOPATH)/bin:$PATH"             # or add it to your shell profile

Or take a signed archive from the latest release — 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:

# --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 the settings a client's configuration would carry: your OAuth client JSON, the profile, read-only, the destructive switch, the sharing tools, the download and upload folder, the largest download, Workspace labels and activity — no config file to edit. Deleting for good and sharing past your organization (enable_destructive), labels (labels) and activity (activity) stay off unless you turn them on, and read-only leaves the destructive switch with nothing to register. 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 a switch off unless you need its tools.

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. Labels and activity also need a login that asks for their scopes, such as google-drive-mcp login --labels=true. Claude Code does not install .mcpb files, so it uses the command below.

Set up Google

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.

2. Enable the Google Drive API for it, under APIs & Services → Library.

3. Configure the OAuth consent screen.

   • On a Google Workspace account, choose Internal. Refresh tokens do not expire.
   • On a personal account, choose External, leave it in Testing, and add your own address as a test user. docs/troubleshooting.md says what Testing means for how long a sign-in lasts.

4. On an External app, add the scopes this server asks for. Google asks for that list only from apps used by people outside your Workspace organization, so an Internal app can skip this step; listing them anyway does no harm. Which ones depends on how you run it, and login requests exactly the set your configuration needs — so add the ones you will use, and re-run login if you turn a feature on later. All of them are restricted scopes, which is fine for an app only you use and never publish.

   Scope	Requested when
   https://www.googleapis.com/auth/drive	always, unless read-only
   https://www.googleapis.com/auth/drive.readonly	instead of it, with GDRIVE_READ_ONLY=true
   https://www.googleapis.com/auth/drive.labels	with GDRIVE_LABELS=true
   https://www.googleapis.com/auth/drive.labels.readonly	with GDRIVE_LABELS=true and read-only
   https://www.googleapis.com/auth/drive.activity.readonly	with GDRIVE_ACTIVITY=true

   google-drive-mcp doctor names any scope your token is missing, which is what to run if a call comes back refused after you change a flag.

5. Create credentials → OAuth client ID → Desktop app, and download the JSON. A Web application client will not work: this server uses the loopback flow Google documents for desktop apps.

6. Put the JSON where the server looks, or point at it:

   mkdir -p ~/.config/google-drive-mcpcp ~/Downloads/client_secret_*.json ~/.config/google-drive-mcp/client_secret.json

7. Log in and check:

   google-drive-mcp logingoogle-drive-mcp doctor

login opens a browser, receives the callback on 127.0.0.1 with PKCE, and stores the refresh token in your OS keyring (Secret Service, Keychain or Credential Manager). If no keyring is available it falls back to a 0600 file and says so. logout revokes the token at Google and deletes it locally.

Logging in over SSH needs the callback port forwarded to your machine; docs/troubleshooting.md shows how.

Connect a client

Claude Code

claude mcp add google-drive -- google-drive-mcp

Claude Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json) take the same shape:

{  "mcpServers": {    "google-drive": {      "command": "google-drive-mcp",      "env": {        "GDRIVE_LOCAL_DIR": "/absolute/path/for/downloads"      }    }  }}

These clients pass only command, args and env, which is why every setting is an environment variable.

Configuration

Every setting is a GDRIVE_* environment variable, most with a matching flag. The full list, with defaults, is in docs/configuration.md. The ones that change what the server will do at all:

Safety

Your MCP client approves each call; the server does not ask you itself. claude.ai and Codex prompt for the tools marked destructive, which is every write but those that only add something new: create_file, create_folder, create_shortcut, upload_file, copy_file, add_comment, download_file and extract_text. VS Code prompts for every tool not marked read-only, which is every tool that writes, download_file included. In Claude Code, delete_file, empty_trash, delete_drive and share_by_link ask on every call whatever your rules say, and are refused where no prompt can be drawn: none can be undone, and each reaches past one item, skipping the trash, taking a whole trash or shared drive, or opening a file to everyone with the link or a whole domain. For the rest, 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-drive. For example, the writes that share, sign off or delete:

{  "permissions": {    "ask": [      "mcp__google-drive__share_file", "mcp__google-drive__share_outside_organization",      "mcp__google-drive__share_by_link", "mcp__google-drive__transfer_ownership",      "mcp__google-drive__resolve_access_request", "mcp__google-drive__lift_drive_restriction",      "mcp__google-drive__approve_file",      "mcp__google-drive__delete_file", "mcp__google-drive__empty_trash",      "mcp__google-drive__delete_drive", "mcp__google-drive__delete_revision",      "mcp__google-drive__delete_comment"    ]  }}

A client that runs with nobody watching can make every write its settings register, so leave GDRIVE_ENABLE_DESTRUCTIVE off for one.

What holds whatever the client does:

• Wide shares are their own tools. share_file grants named people and groups inside your organization. Outside means an address whose domain is not your account's; on a personal Google account, which has no organization, that is every address.
• Nothing widens by omission. A move, a copy, or a folder's limited access turned off that would let anyone with the link, a domain or someone outside your organization reach a file is refused, naming who. Accepting a request for access from outside your organization is refused too.
• Deletes need the flag and confirm: true. confirm: true is the caller's witness that it meant this delete, not your approval. There is no bulk delete and no bulk share, and deleting the top of a drive is refused outright. The one thing deleted for good without either is the temporary copy extract_text makes and removes within the same call.
• A Markdown file keeps its comments. Google Docs edits a .md stored in Drive in place and writes the comments made there into the file's own text. update_content refuses new content that would lose one unless allow_comment_changes is set.
• dry_run previews the writes that move, share, copy, trash, grant or destroy, and sends nothing.

docs/security.md has the threat model.

Getting help

Run google-drive-mcp doctor first. It checks the credentials, the granted scopes and what Google answers, and names what is missing; most first-run trouble is an API that was never enabled or a consent screen without you on it. docs/troubleshooting.md covers each failure.

google-drive-mcp status --json prints the setup as one JSON object, without contacting Google, for a script that has to decide whether this server is authorized before starting it; the shape is in docs/configuration.md.

Then open an issue with what troubleshooting lists. Never paste a file id or URL, file contents, a client JSON, a token or a tool result; describe the shape instead.

Versioning

Tool names, their arguments and the shape of their output are stable within a major version. A change that needs you to do something, such as a new scope, another login or a different command in your client config, is marked Breaking: in CHANGELOG.md, which is what the release notes are made from. A tool moving from the default surface to behind a setting, or the other way, counts as breaking.

Documentation

• docs/configuration.md: every setting, where state is stored, and reading the setup from a script.
• docs/troubleshooting.md: symptoms and their fixes, then rotating the token, revoking access and handling a suspected exposure.
• docs/security.md: the threat model.
• docs/architecture.md: how it works, and the design decisions a contributor should not undo.
• docs/release.md: how a release is cut and checked.
• CONTRIBUTING.md: the gates, the live run and the review flow.
• CHANGELOG.md: what each release changed.

Contributing

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

Security

SECURITY.md says how to report a vulnerability. Please do not open a public issue for one.

Code of conduct

CODE_OF_CONDUCT.md: the Contributor Covenant 3.0.

License

Apache-2.0. See LICENSE.