Gdrive Sa

A reusable, project-agnostic Google Drive integration for Claude Code.

Give Claude read access to any Google Drive folder — anyone's Drive — by having them share the folder with a single service-account email. No OAuth dance, no per-user browser login, no test-user allowlists, no tokens that expire.

Built once for the-artrobe project, extracted here so the same setup drops into any project.

---

Why a service account (and not OAuth)?

We first tried the deprecated @modelcontextprotocol/server-gdrive (OAuth). It works, but:

• It authenticates one Google identity and needs a browser OAuth flow every time the token rotates.
• To read someone else's Drive, that person must be added as a test user in your Google Cloud app and click through a consent screen — impractical for clients/collaborators.
• The token lives on one machine and expires.

A service account fixes all of this:

	OAuth	Service account (this repo)
Read your own Drive	✅	✅
Read someone else's Drive	they must be a test user + consent	they just share a folder with an email
Browser login needed	yes	no
Token expiry	yes	no (key is self-contained)
Works headless / on a server	painful	✅
Tied to a specific GCP project	—	no — the key is self-contained; swap keys freely

The JSON key is fully self-contained — it carries its own project_id, client_email, and private key. The server reads whatever key you point it at, so it never cares which GCP project the key came from. Different project next time? Just drop in a different key.

---

What Claude gets

Three tools, read-only (drive.readonly scope):

Tool	What it does
search	Find files by name or Drive query syntax
list	List everything shared with the service account, or a folder's contents by folderId
download	Download a file by fileId — returns text inline, or writes binary to a savePath

Works with Shared Drives too (supportsAllDrives / includeItemsFromAllDrives).

---

Setup (~10 minutes, one time per machine)

Part A — Google Cloud Console

Do all of this signed in as the Google account that will own the service account (the account doesn't need to own the Drive files — folders get shared with it later).

1. Project — go to console.cloud.google.com → create or select any project. The name doesn't matter; the key is self-contained.
2. Enable the API — ☰ → APIs & Services → Library → search Google Drive API → Enable.
3. Create the service account — ☰ → IAM & Admin → Service Accounts → + Create Service Account → give it a name (e.g. drive-reader) → Create and Continue → skip the role step → Done.
4. Create a JSON key — click the new service account → Keys tab → Add Key → Create new key → JSON → Create. A .json file downloads. This is the credential.
5. Copy the service-account email — looks like drive-reader@<project>.iam.gserviceaccount.com. You'll share folders with this address.

Service accounts and the Drive API are free. You do not need to enable billing. (A service account gets its own empty 15 GB Drive, but that only matters if you upload as the service account — irrelevant for reading folders people share with it.)

Part B — Install on this machine

git clone <this-repo> gdrive-mcp-setup
cd gdrive-mcp-setup

# 1. put the key somewhere safe & lock it down
mkdir -p ~/.config/gdrive-sa
cp /path/to/downloaded-key.json ~/.config/gdrive-sa/key.json
chmod 600 ~/.config/gdrive-sa/key.json     # private key — never commit it

# 2. install deps
npm install

# 3. sanity check the key + connection
npm run smoke-test

smoke-test reads the key, prints the project/email, and does one list call. Empty result is expected until you share a folder.

Part C — Register with Claude Code

claude mcp add gdrive-sa \
  -s user \
  -e GDRIVE_SA_KEY="$HOME/.config/gdrive-sa/key.json" \
  -- node "$(pwd)/src/server.mjs"

Then confirm:

claude mcp list
# gdrive-sa: node .../src/server.mjs - ✓ Connected

Restart Claude Code — MCP servers load at startup. The search / list / download tools are then available in-session.

---

Using it — sharing folders

To give Claude access to any Drive folder (yours or someone else's):

1. Open the folder in Google Drive → Share
2. Paste the service-account email (...@<project>.iam.gserviceaccount.com)
3. Give it Viewer → Send

That folder is now readable through the MCP. No further config, ever. To revoke: un-share it.

---

Multiple accounts / projects

Everything keys off a path, so scaling is trivial:

• Different Drives, same service account — just have each person share a folder with the one email. Nothing to change.
• A second, isolated service account — put its key at a different path and register a second server:

  claude mcp add gdrive-sa-clientB -s user \
    -e GDRIVE_SA_KEY="$HOME/.config/gdrive-sa/clientB.json" \
    -- node "$(pwd)/src/server.mjs"
  

  Both connect at once, searchable independently.

---

Security

• Never commit key.json — it's a private key. This repo's .gitignore blocks *.json key patterns; keep the key in ~/.config/gdrive-sa/, not in a project.
• Scope is drive.readonly — the server cannot modify or delete anything.
• The service account only sees folders explicitly shared with it — not your whole Drive.
• If a key leaks, delete it in Cloud Console (Service Accounts → Keys) and issue a new one. Google also auto-disables keys it detects in public repos.

---

Files

src/server.mjs        the MCP server (googleapis + service-account auth)
scripts/smoke-test.mjs verify key + connection before registering
scripts/install.sh    optional guided installer
package.json          deps: googleapis, @modelcontextprotocol/sdk
.gitignore            blocks credential files

Troubleshooting

• list returns [] — nothing is shared with the service account yet. Share a folder.
• claude mcp list shows not connected — check GDRIVE_SA_KEY points at a real file and run npm run smoke-test.
• Google Drive API has not been used… — enable the Drive API on the key's project (Part A.2).
• HEIC/MOV files — Drive stores them fine; converting for web is a separate step (pillow-heif for HEIC, ffmpeg for MOV). Out of scope for this MCP.