gdrive-mcp

A local, read-only MCP server for searching your Google Drive.

Tools exposed:

Tool	What it does
search_drive_by_name	Fuzzy, typo-tolerant search over file/folder names (primary tool).
search_drive_by_content	Full-text search inside file contents (Docs, PDFs, …).
list_drive_folder	List the direct children of a folder by ID (root = My Drive).

It runs locally over stdio, authenticates once with your Google account via a browser, and caches the token in ~/.gdrive-mcp/token.json. The only Google scope requested is drive.readonly — it cannot modify or delete anything.

Fuzzy search note: Google Drive's API only supports substring matching, so this server pulls a candidate pool (substring matches + recent files) and re-ranks them client-side with Fuse.js for typo tolerance.

---

1. Provision the Google OAuth app (one time, ~5 min)

You need a Google Cloud project with the Drive API enabled and an OAuth client.

1. Go to https://console.cloud.google.com/ and create a new project (e.g. "gdrive-mcp"). Select it.
2. Enable the Drive API: APIs & Services → Library → search "Google Drive API" → Enable.
3. Configure the OAuth consent screen: APIs & Services → OAuth consent screen.
   • User type: External (unless you're on Google Workspace and want Internal).
   • Fill in app name, your support email, developer email. Save.
   • Scopes: you can skip adding scopes here (the app requests drive.readonly at runtime).
   • Test users: add your own Google account (lio.lunesu@defang.io). While the app is in "Testing" status this is required, and the token works indefinitely for test users.
4. Create credentials: APIs & Services → Credentials → Create Credentials → OAuth client ID.
   • Application type: Desktop app.
   • Name it, Create, then Download JSON.
5. Save that file as ~/.gdrive-mcp/credentials.json:

   mkdir -p ~/.gdrive-mcp
   mv ~/Downloads/client_secret_*.json ~/.gdrive-mcp/credentials.json
   

   (Or put it anywhere and set GOOGLE_CREDENTIALS_PATH to its path.)

---

2. Build & log in

Node is provided by Nix + direnv — no system Node needed. From the project dir:

direnv allow          # first time only; loads node from flake.nix
npm install
npm run login         # builds, opens browser, caches token to ~/.gdrive-mcp/token.json

(Without direnv you can run anything via nix develop -c <cmd>, e.g. nix develop -c npm run login.)

A browser tab opens asking you to grant read-only Drive access. Approve it; the tab says "Authorized" and the token is saved. You only do this once (it auto-refreshes).

Google may warn the app is "unverified" since it's your own test app — click Advanced → Go to … (unsafe) to continue. That's expected for a personal app.

---

3. Register with your MCP client

Because Node comes from Nix/direnv (not your system PATH), launch the server with direnv exec so it picks up the flake's Node regardless of how the MCP client's own environment is set up.

Claude Code:

claude mcp add gdrive -- direnv exec /Users/llunesu/repos/gdrivemcp node /Users/llunesu/repos/gdrivemcp/dist/index.js

Claude Desktop / generic (claude_desktop_config.json or equivalent):

{
  "mcpServers": {
    "gdrive": {
      "command": "direnv",
      "args": [
        "exec",
        "/Users/llunesu/repos/gdrivemcp",
        "node",
        "/Users/llunesu/repos/gdrivemcp/dist/index.js"
      ]
    }
  }
}

(If you have a system Node and don't care about pinning, "command": "node" with just the script path also works.)

If you stored credentials somewhere other than ~/.gdrive-mcp/credentials.json, add "env": { "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json" }.

---

Development

npm run dev     # tsc --watch
npm run build   # one-off compile to dist/

Notes & limits

• Read-only by design — scope is drive.readonly, no write methods are called.
• Searches My Drive for the signed-in user (not Shared Drives; flip includeItemsFromAllDrives/corpora in src/drive.ts if you need those).
• Fuzzy search fetches up to ~500 candidate files per query to rank locally; for very large Drives you may want to tighten the caps in searchByName.
• Reading/exporting file content is intentionally not included — these tools find and list files only.