mcp-google-drive: Instructions file for Claude Code

CLAUDE.md — mcp-google-drive

MCP server for the Google Drive API v3 (TypeScript, stdio). Mixed read/write: tools cover search/listing (incl. shared drives), file metadata and organization (folders, copy, move, rename), content transfer (multipart upload with Workspace import, binary download, export of Google-native files), the reversible trash explicitly separated from permanent deletion, permissions/sharing and Drive comments; raw_request is the escape hatch. The server talks to https://www.googleapis.com (drive/v3 + upload/drive/v3) with a Bearer token; the token is minted from an OAuth2 refresh token via https://oauth2.googleapis.com/token (or a static GOOGLE_DRIVE_ACCESS_TOKEN, mostly for testing). Docs/Sheets/Slides content is never edited — those files are moved, shared, exported and converted as opaque units.

Commands

npm run dev        # run from source (tsx watch)
npm test           # unit tests + dist smoke, no network
npm run typecheck  # types for src + tests
npm run build      # emit dist/
npm run smoke      # live check: read-only by default (about + optional GOOGLE_DRIVE_SMOKE_FILE_ID);
                   # GOOGLE_DRIVE_SMOKE_WRITE=1 = disposable write scenario with cleanup in finally

Architecture

• src/config.ts — env → config. Credentials: either the refresh triple GOOGLE_DRIVE_CLIENT_ID + GOOGLE_DRIVE_CLIENT_SECRET + GOOGLE_DRIVE_REFRESH_TOKEN (all three or ConfigError incomplete_oauth_config) or GOOGLE_DRIVE_ACCESS_TOKEN; optional GOOGLE_DRIVE_API_BASE, GOOGLE_DRIVE_TIMEOUT_MS, GOOGLE_DRIVE_MAX_RETRIES. No credentials at all is NOT an error: the fields stay undefined and the server starts degraded. Also home to CredentialsError / MISSING_CREDENTIALS_MESSAGE (opens with the historical startup error verbatim, then names the variables and the restart) and hasCredentials().
• src/client.ts — all HTTP and all wire mapping. Token lifecycle (cache until ~60s before expiry, dedupe concurrent refreshes, one forced re-mint + replay on 401). Every call — JSON, multipart upload, binary download — goes through the private send(): it resolves the path against the base and rejects foreign origins (SSRF guard), enforces an AbortController timeout that also covers reading the body (read as bytes, never text — downloads are binary), retries 429 always but 5xx/network errors only for GET — replaying a write after an ambiguous failure would duplicate it — and throws GoogleDriveError(status, body). Typed per-endpoint methods own the wire vocabulary: buildSearchQuery() escapes user values into the Drive q syntax, moveFile() computes addParents/removeParents from the current parents, buildMultipartBody() frames metadata + media, supportsAllDrives rides on every file call, and the comments endpoints always get the explicit fields they require.
• src/tools/search.ts — search_files, list_shared_drives. src/tools/files.ts — get_file, create_folder, copy_file, move_file, update_file_metadata. src/tools/content.ts — upload_file, download_file, export_file + the local-path/inline-delivery helpers (absolute paths only, no silent overwrite, 100 KB inline cap, extension→mimeType guessing). src/tools/trash.ts — trash_file (trash/restore) and delete_file_forever, deliberately two tools. src/tools/permissions.ts — manage_permissions (list/share/update/remove). src/tools/comments.ts — manage_comments (list/get/create/reply/resolve/reopen/delete). src/tools/raw.ts — raw_request (GET/POST/PATCH/DELETE). src/tools/util.ts — ok/fail, the four annotation presets (READ_ONLY/WRITE/UPDATE/DESTRUCTIVE), safeLocalPath and shared zod schema factories (fileIdSchema, folderIdSchema, localPathSchema).
• src/index.ts — wires every register* into the McpServer. loadConfigOrDegraded() catches ConfigError, pings startup_failed (fire-and-forget) and degrades the config to "no credentials"; an unconfigured start prepends UNCONFIGURED_PREFIX — plus Configuration problem: <message> when a ConfigError was caught — to the initialize instructions, and oninitialized sends server_start for a configured install or unconfigured_start (with the reason) otherwise.
• src/telemetry.ts — anonymous usage pings (ids/names/versions only, never data or arguments; fire-and-forget, must never block or throw; opt-out ASKADS_TELEMETRY=0). server_start means "a usable install started"; unconfigured_start is a degraded start and startup_failed a malformed config caught at load — both carry a reason from a closed vocabulary (missing_credentials, incomplete_oauth_config) — never a variable's name or value.