google-drive-mcp

A local MCP server that gives Claude Code full-scope Google Drive access — search, read, upload, rename, move, and change sharing permissions — including on files that already exist in your Drive (not just ones this app creates).

It requests the broad https://www.googleapis.com/auth/drive scope on purpose, because the tasks it's built for (renaming, moving, and changing sharing on existing course files) are impossible with the narrower drive.file scope.

---

One-time setup

You do this once. After that, every Claude Code session can use the google-drive tools.

Step 1 — Create a Google Cloud project (skip if you already have one)

1. Go to https://console.cloud.google.com/.
2. Top bar → project dropdown → New Project.
3. Name it something like app-integrations → Create. Wait a few seconds, then make sure that project is selected in the top bar.

Step 2 — Enable the Google Drive API

1. Go to https://console.cloud.google.com/apis/library/drive.googleapis.com.
2. Confirm your project is selected → click Enable.

Step 3 — Configure the OAuth consent screen

1. Go to https://console.cloud.google.com/auth/overview (APIs & Services → OAuth consent screen).
2. If prompted, choose User Type: External → Create. (External is fine for a personal Google account; you'll just be a "test user".)
3. Fill the required fields:
   • App name: google-drive-mcp (anything is fine)
   • User support email: your email
   • Developer contact email: your email
   • Save and continue.
4. Scopes page: you don't have to add scopes here — the server requests them at auth time. Save and continue.
5. Test users page: click + Add users and add your own Google email (your own Google account). This is required while the app is in "Testing". Save and continue.

You do not need to publish the app or go through Google verification. A Testing-status app works indefinitely for the test users you list; a refresh token for a Testing app can expire after 7 days of disuse — if Drive tools ever start failing with an auth error, just re-run npm run auth (Step 6).

Step 4 — Create the OAuth client (Desktop app)

1. Go to https://console.cloud.google.com/auth/clients (APIs & Services → Credentials).
2. + Create Credentials → OAuth client ID.
3. Application type: Desktop app. Name it desktop-mcp → Create.
4. In the dialog, click Download JSON.

Step 5 — Put the client file where the server expects it

Save that downloaded JSON to exactly this path/name:

~/.config/google-drive-mcp/gcp-oauth.keys.json

For example, if it downloaded to ~/Downloads/client_secret_XXXX.json:

mkdir -p ~/.config/google-drive-mcp
mv ~/Downloads/client_secret_*.json ~/.config/google-drive-mcp/gcp-oauth.keys.json

Step 6 — Authorize (one time)

cd ~/mcp-servers/google-drive-mcp
npm run auth

This prints a URL and opens your browser. Sign in with the Google account whose Drive you want to manage. You'll see a "Google hasn't verified this app" warning (expected, because the app is in Testing) → Advanced → Go to google-drive-mcp (unsafe) → Continue → allow the Drive permission.

On success it writes ~/.config/google-drive-mcp/.gdrive-credentials.json (your refresh token — keep it private; it's already chmod 600).

Step 7 — Use it

The server is already registered in ~/.claude.json under the name google-drive. Start a new Claude Code session and the gdrive_* tools will be available. (MCP servers load at session start, so a session started before registration won't see them.)

Quick manual smoke test (optional):

cd ~/mcp-servers/google-drive-mcp && npm start
# prints "google-drive-mcp: connected over stdio", then waits. Ctrl-C to quit.

---

Tools

Tool	What it does
gdrive_search	Search with a Drive q query (e.g. name contains 'syllabus')
gdrive_list_recent	List recently-modified files
gdrive_list_children	List the direct children of a folder (trashed items excluded by default)
gdrive_get_metadata	Metadata + links for one file
gdrive_get_links	Get open-in-new-tab + iframe .../preview embed links
gdrive_create_folder	Create a folder (optionally nested)
gdrive_upload_file	Upload a local file by path (streamed — good for big PDFs)
gdrive_create_text_file	Create a text file from inline content
gdrive_copy	Copy a file (not folders — the Drive API can't copy a folder in one call)
gdrive_create_shortcut	Point a shortcut at an existing file/folder so one item can live in several places
gdrive_rename	Rename a file/folder
gdrive_move	Move via add/remove parents
gdrive_trash	Move to trash — reversible, Drive keeps it 30 days
gdrive_untrash	Restore from trash
gdrive_delete	Permanent delete, no trash, unrecoverable — guarded (see below)
gdrive_list_permissions	List permissions (emails + roles)
gdrive_share	Add a permission — {type:'anyone',role:'reader'} = link-Viewer; {type:'user',role:'writer',emailAddress:...} = Editor
gdrive_unshare	Remove a permission by id

Deleting things

gdrive_trash is the one to reach for. It's reversible, Drive holds trashed items for 30 days, and gdrive_untrash puts them back where they were.

gdrive_delete is permanent and unrecoverable — nothing lands in the trash. It requires a confirmName that exactly matches the item's current name, which forces a metadata read before anything is destroyed, so a stale or mistyped file ID fails loudly instead of deleting the wrong thing. Deleting a folder takes everything inside it.

Registration

Registered in both configs — they are read independently, so registering in one does not make the server available in the other:

• ~/.claude.json (Claude Code)
• ~/Library/Application Support/Claude/claude_desktop_config.json (Desktop / Cowork)

Identical entry in each:

"google-drive": {
  "command": "/opt/homebrew/bin/node",
  "args": ["/ABSOLUTE/PATH/TO/mcp-servers/google-drive-mcp/index.js"]
}

The absolute path to node is required, not a style choice. An app launched from Finder or at login inherits the minimal launchd PATH (/usr/bin:/bin:/usr/sbin:/sbin), in which Homebrew's /opt/homebrew/bin/node is invisible entirely. A bare "node" works every time you test it from a terminal and fails every morning. ~/mcp-servers/trello-mcp/doctor.py checks every server in both configs for this.

If you install the claude CLI later, the equivalent command is:

claude mcp add --scope user google-drive -- /opt/homebrew/bin/node ~/mcp-servers/google-drive-mcp/index.js

Files

• index.js — the MCP server (tool definitions)
• auth.js — one-time npm run auth loopback OAuth flow
• lib-auth.js — shared OAuth/config helpers
• ~/.config/google-drive-mcp/gcp-oauth.keys.json — you provide (Step 5)
• ~/.config/google-drive-mcp/.gdrive-credentials.json — created by npm run auth

---

For the resume / portfolio

Kept here so a future resume session has the honest version rather than reconstructing it.

Why this exists when a Drive connector already does. It extends the built-in connector rather than replacing it. The gap is bulk work: renaming a hundred files after a naming convention changes mid-project is tedious by hand, trivial to script, and worth solving permanently rather than once. That was the motivating case.

What I actually did: set the goal and the constraint — a free solution that saves the same time on every future project, not a one-off script for one folder.

Known operational caveat: the OAuth app's publishing status governs how long refresh tokens last. In "Testing" they expire roughly weekly (invalid_grant); publishing the app removes that limit for every integration sharing the Cloud project.

Portfolio-length bullet: see the shared version in ~/mcp-servers/trello-mcp/README.md — these three are best described together.

Full case study: https://zeno-blade-creator.github.io/projects/personal-integrations.html