mcp-google-gdrive 2.0.0 → 2.2.0

package/README.md

@@ -19,6 +19,7 @@ An [MCP](https://modelcontextprotocol.io/) server for Google Drive, Docs, Sheets
 | `gdrive_list_files` | List files with optional search query and folder filtering |
 | `gdrive_get_metadata` | Get detailed metadata for a file by ID |
 | `gdrive_read_file` | Read file content with automatic Workspace format conversion |
+| `gdrive_download_file` | Download a file to local disk (supports Workspace export) |
 | `gdrive_create_file` | Create a new file with optional OCR on image/PDF uploads |
 | `gdrive_update_file` | Update a file's content, name, or description |
 | `gdrive_copy_file` | Copy a file, optionally to a different folder |
@@ -64,7 +65,7 @@ An [MCP](https://modelcontextprotocol.io/) server for Google Drive, Docs, Sheets
 
 | Tool | Description |
 |------|-------------|
-| `gdrive_export_doc` | Export a Google Doc (markdown, html, text, docx, pdf) |
+| `gdrive_export_doc` | Export a Google Doc (markdown, html, text, docx, pdf). Use `savePath` to save binary formats to disk |
 | `gdrive_create_doc` | Create a Google Doc from Markdown content |
 | `gdrive_update_doc` | Replace a Google Doc's content with Markdown |
 
@@ -73,7 +74,7 @@ An [MCP](https://modelcontextprotocol.io/) server for Google Drive, Docs, Sheets
 | Tool | Description |
 |------|-------------|
 | `gdrive_create_sheet` | Create a new spreadsheet with named tabs |
-| `gdrive_export_sheet` | Export a sheet to CSV, JSON, or XLSX |
+| `gdrive_export_sheet` | Export a sheet to CSV, JSON, or XLSX. Use `savePath` to save XLSX to disk |
 | `gdrive_list_sheets` | List all sheets/tabs in a spreadsheet |
 | `gdrive_read_sheet_range` | Read a specific range from any tab (A1 notation) |
 | `gdrive_write_sheet_range` | Write data to a specific range |
@@ -83,9 +84,41 @@ An [MCP](https://modelcontextprotocol.io/) server for Google Drive, Docs, Sheets
 | Tool | Description |
 |------|-------------|
 | `gdrive_create_slides` | Create a new presentation |
-| `gdrive_export_slides` | Export slides to text, PDF, or PPTX |
+| `gdrive_export_slides` | Export slides to text, PDF, or PPTX. Use `savePath` to save binary formats to disk |
 | `gdrive_get_slide_thumbnail` | Get a thumbnail image URL for a specific slide |
 
+## What's New in v2.2
+
+- **`outputFormat` parameter** — 12 read/list tools now accept `outputFormat: "json" | "yaml" | "text"`. Default is `json` (backwards compatible). Use `yaml` for structured output or `text` for compact human-readable tables. Supported on: `list_accounts`, `list_files`, `list_folder`, `list_trash`, `list_permissions`, `list_labels`, `list_file_labels`, `list_sheets`, `get_metadata`, `read_sheet_range`, `get_slide_thumbnail`, `search_files`.
+
+### v2.1
+
+- **`gdrive_download_file`** — Download any file from Drive to a local disk path. Workspace files (Docs, Sheets, Slides) are automatically exported to the specified format (pdf, docx, xlsx, pptx, csv, txt, html, or markdown).
+- **`savePath` on export tools** — `gdrive_export_doc`, `gdrive_export_sheet`, and `gdrive_export_slides` now accept an optional `savePath` parameter. When provided, binary exports (docx, pdf, xlsx, pptx) are saved to disk instead of returned as base64. Omitting `savePath` preserves the v2.0 behavior.
+- **`gdrive_list_accounts` email resolution** — Accounts migrated from v0.x that showed "migrated" instead of an email address now auto-resolve via the Google userinfo API on first call.
+- **Documentation fixes** — `gdrive_empty_trash` notes eventual consistency; `gdrive_transfer_ownership` notes cross-org limitation.
+
+## Output Formats
+
+All read and list tools support an `outputFormat` parameter:
+
+| Format | Description | Use Case |
+|--------|-------------|----------|
+| `json` | Pretty-printed JSON (default) | Machine consumption, API pipelines |
+| `yaml` | YAML serialization | Human-readable structured data, config files |
+| `text` | Compact aligned tables and key-value pairs | Quick scanning, terminal output, token-efficient LLM context |
+
+Example: `gdrive_list_files({ query: "name contains 'report'", outputFormat: "text" })` returns:
+
+```
+files:
+  id             name              mimeType         modifiedTime  size
+  -------------  ----------------  ---------------  ------------  ----
+  abc123def456   Q1 Report.pdf     application/pdf  2026-04-01    1024
+  ghi789jkl012   Q2 Report.docx    application/pdf  2026-03-15    2048
+resultCount: 2
+```
+
 ## Prerequisites
 
 - Node.js 18+

package/SPEC.md

@@ -9,17 +9,19 @@ MCP server providing Claude Code with full read/write access to a personal Googl
 | Item | Value |
 |------|-------|
 | Package name | mcp-google-gdrive |
-| Version | 0.1.0 |
-| Runtime | Node.js 18+ (ESM), verified 22.22.0 in WSL |
+| Version | 2.2.0 |
+| Runtime | Node.js 18+ (ESM) |
 | MCP SDK | @modelcontextprotocol/sdk ^1.26.0 |
 | Validation | zod ^3.25.0 |
-| Auth | Google OAuth2 (desktop app flow) |
-| API | Google Drive API v3 |
-| Extra deps | googleapis ^144.0.0, turndown ^7.2.0, marked ^15.0.0 |
-| Location | WSL ~/projects/mcp-servers/mcp-google-gdrive/ |
+| Auth | Google OAuth2 (desktop app flow), multi-account |
+| API | Google Drive API v3, Docs v1, Sheets v4, Slides v1, Labels v2 |
+| Deps | googleapis ^144.0.0, turndown ^7.2.0, js-yaml ^4.1.1 |
+| Source | github.com/sleepytimeshon/mcp-google-gdrive |
+| npm | npmjs.com/package/mcp-google-gdrive |
 | Entry point | src/index.js |
 | Transport | stdio (JSON-RPC) |
 | License | MIT |
+| Tools | 38 across 9 categories |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-gdrive",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "MCP server for Google Drive, Docs, Sheets, and Slides with multi-account support, permissions, labels, and full CRUD",
   "type": "module",
   "bin": {
@@ -33,6 +33,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "googleapis": "^144.0.0",
+    "js-yaml": "^4.1.1",
     "turndown": "^7.2.0",
     "zod": "^3.25.0"
   }

package/src/index.js

@@ -5,8 +5,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { google } from "googleapis";
 import TurndownService from "turndown";
+import yaml from "js-yaml";
 import { readFile, writeFile, mkdir, chmod } from "node:fs/promises";
-import { join } from "node:path";
+import { join, resolve, dirname } from "node:path";
 import { homedir } from "node:os";
 import { existsSync } from "node:fs";
 import { createInterface } from "node:readline";
@@ -228,6 +229,30 @@ function sanitizeDriveId(id) {
   return id;
 }
 
+function validateSavePath(savePath) {
+  const resolved = resolve(savePath);
+  if (resolved.includes("\0")) {
+    throw new Error("Invalid save path: null bytes not allowed");
+  }
+  return resolved;
+}
+
+async function saveToDisk(data, savePath) {
+  const resolved = validateSavePath(savePath);
+  await mkdir(dirname(resolved), { recursive: true });
+  const buf = Buffer.from(data);
+  await writeFile(resolved, buf);
+  return { path: resolved, size: buf.length };
+}
+
+async function handleBinaryExport(data, format, savePath) {
+  if (savePath) {
+    const result = await saveToDisk(data, savePath);
+    return jsonResponse({ exported: format.toUpperCase(), path: result.path, size: result.size });
+  }
+  return binaryResponse(data, format.toUpperCase());
+}
+
 function markdownToHtml(md) {
   return md
     .replace(/^### (.+)$/gm, "<h3>$1</h3>")
@@ -239,6 +264,41 @@ function markdownToHtml(md) {
     .replace(/^/, "<p>").replace(/$/, "</p>");
 }
 
+// ─── Output Format ──────────────────────────────────────────────────────────
+
+const OUTPUT_FORMAT_SCHEMA = z.enum(["json", "yaml", "text"]).optional().default("json").describe("Output format: json (default), yaml, or text (compact human-readable)");
+
+function dataToText(data) {
+  if (Array.isArray(data) && data.length > 0 && typeof data[0] === "object") {
+    const keys = Object.keys(data[0]);
+    const widths = keys.map(k => k.length);
+    for (const row of data) { keys.forEach((k, i) => { const len = String(row[k] ?? "").length; if (len > widths[i]) widths[i] = len; }); }
+    const pad = (val, i) => String(val ?? "").padEnd(widths[i]);
+    const header = keys.map((k, i) => pad(k, i)).join("  ");
+    const sep = widths.map(w => "-".repeat(w)).join("  ");
+    const rows = data.map(row => keys.map((k, i) => pad(row[k], i)).join("  "));
+    return [header, sep, ...rows].join("\n");
+  }
+  if (Array.isArray(data) && data.length > 0 && Array.isArray(data[0])) {
+    return data.map(row => (row || []).map(c => String(c ?? "")).join("\t")).join("\n");
+  }
+  if (typeof data === "object" && data !== null) {
+    return Object.entries(data).map(([k, v]) => {
+      if (Array.isArray(v) && v.length > 0 && typeof v[0] === "object") return `${k}:\n${dataToText(v).split("\n").map(l => "  " + l).join("\n")}`;
+      if (Array.isArray(v)) return `${k}: ${v.join(", ")}`;
+      if (typeof v === "object" && v !== null) return `${k}: ${JSON.stringify(v)}`;
+      return `${k}: ${v}`;
+    }).join("\n");
+  }
+  return String(data);
+}
+
+function formatOutput(data, format) {
+  if (format === "yaml") return textResponse(yaml.dump(data, { lineWidth: 120, noRefs: true }));
+  if (format === "text") return textResponse(dataToText(data));
+  return jsonResponse(data);
+}
+
 const FILE_FIELDS = "id,name,mimeType,size,createdTime,modifiedTime,parents,webViewLink,owners,shared,description,trashed,starred";
 const LIST_FIELDS = "id,name,mimeType,modifiedTime,size,parents";
 
@@ -253,15 +313,34 @@ const server = new McpServer({
 
 server.registerTool("gdrive_list_accounts", {
   description: "List all configured Google accounts with their labels and email addresses.",
-  inputSchema: {},
+  inputSchema: {
+    outputFormat: OUTPUT_FORMAT_SCHEMA,
+  },
   annotations: { readOnlyHint: true, openWorldHint: false },
-}, async () => {
+}, async ({ outputFormat }) => {
   try {
     const config = await loadConfig();
+    const unresolved = Object.entries(config.accounts)
+      .filter(([, info]) => info.email === "migrated" || !info.email);
+    if (unresolved.length > 0) {
+      const results = await Promise.all(unresolved.map(async ([label]) => {
+        try {
+          const auth = await authorizeAccount(label);
+          const oauth2 = google.oauth2({ version: "v2", auth });
+          const userInfo = await oauth2.userinfo.get();
+          return { label, email: userInfo.data.email };
+        } catch { return null; }
+      }));
+      let configDirty = false;
+      for (const r of results) {
+        if (r?.email) { config.accounts[r.label].email = r.email; configDirty = true; }
+      }
+      if (configDirty) await saveConfig(config);
+    }
     const accounts = Object.entries(config.accounts).map(([label, info]) => ({
       label, email: info.email, active: label === config.active,
     }));
-    return jsonResponse({ accounts, activeAccount: config.active });
+    return formatOutput({ accounts, activeAccount: config.active }, outputFormat);
   } catch (err) { return errorResponse(err.message); }
 });
 
@@ -311,10 +390,11 @@ server.registerTool("gdrive_list_files", {
     pageSize: z.number().optional().default(20).describe("Results per page (max 100, default: 20)"),
     pageToken: z.string().optional().describe("Token for next page of results"),
     orderBy: z.string().optional().default("modifiedTime desc").describe("Sort order"),
+    outputFormat: OUTPUT_FORMAT_SCHEMA,
     account: z.string().optional().describe("Account label (default: active account)"),
   },
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-}, async ({ query, folderId, pageSize, pageToken, orderBy, account }) => {
+}, async ({ query, folderId, pageSize, pageToken, orderBy, outputFormat, account }) => {
   try {
     const { drive } = await getClients(account);
     let q = "trashed = false";
@@ -325,7 +405,7 @@ server.registerTool("gdrive_list_files", {
       orderBy: orderBy || "modifiedTime desc", fields: `nextPageToken,files(${LIST_FIELDS})`,
       supportsAllDrives: true, includeItemsFromAllDrives: true,
     });
-    return jsonResponse({ files: res.data.files || [], nextPageToken: res.data.nextPageToken || null, resultCount: (res.data.files || []).length });
+    return formatOutput({ files: res.data.files || [], nextPageToken: res.data.nextPageToken || null, resultCount: (res.data.files || []).length }, outputFormat);
   } catch (err) { return errorResponse(err.message); }
 });
 
@@ -333,14 +413,15 @@ server.registerTool("gdrive_get_metadata", {
   description: "Get detailed metadata for a specific file in Google Drive.",
   inputSchema: {
     fileId: z.string().describe("Google Drive file ID"),
+    outputFormat: OUTPUT_FORMAT_SCHEMA,
     account: z.string().optional().describe("Account label (default: active account)"),
   },
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-}, async ({ fileId, account }) => {
+}, async ({ fileId, outputFormat, account }) => {
   try {
     const { drive } = await getClients(account);
     const res = await drive.files.get({ fileId, fields: FILE_FIELDS, supportsAllDrives: true });
-    return jsonResponse(res.data);
+    return formatOutput(res.data, outputFormat);
   } catch (err) { return errorResponse(err.code === 404 ? `File not found: ${fileId}` : err.message); }
 });
 
@@ -384,6 +465,46 @@ server.registerTool("gdrive_read_file", {
   } catch (err) { return errorResponse(err.code === 404 ? `File not found: ${fileId}` : err.message); }
 });
 
+server.registerTool("gdrive_download_file", {
+  description: "Download a file from Google Drive to a local disk path. For Workspace files (Docs/Sheets/Slides), exports to the specified format first.",
+  inputSchema: {
+    fileId: z.string().describe("Google Drive file ID"),
+    savePath: z.string().describe("Local file path to save to (absolute or relative)"),
+    exportFormat: z.enum(["pdf", "docx", "xlsx", "pptx", "csv", "txt", "html", "markdown"]).optional().describe("Export format for Workspace files (default: pdf for Docs/Slides, csv for Sheets)"),
+    account: z.string().optional().describe("Account label (default: active account)"),
+  },
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+}, async ({ fileId, savePath, exportFormat, account }) => {
+  try {
+    const { drive } = await getClients(account);
+    const meta = await drive.files.get({ fileId, fields: "id,name,mimeType,size", supportsAllDrives: true });
+    const { name, mimeType, size } = meta.data;
+
+    const workspaceExportMap = {
+      "application/vnd.google-apps.document": { default: "pdf", mimeTypes: { pdf: "application/pdf", docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document", txt: "text/plain", html: "text/html", markdown: "text/html" } },
+      "application/vnd.google-apps.spreadsheet": { default: "csv", mimeTypes: { csv: "text/csv", xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", pdf: "application/pdf" } },
+      "application/vnd.google-apps.presentation": { default: "pdf", mimeTypes: { pdf: "application/pdf", pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation", txt: "text/plain" } },
+    };
+
+    const wsConfig = workspaceExportMap[mimeType];
+    let data;
+
+    if (wsConfig) {
+      const fmt = exportFormat || wsConfig.default;
+      const exportMime = wsConfig.mimeTypes[fmt];
+      if (!exportMime) return errorResponse(`Unsupported export format "${fmt}" for ${mimeType}. Available: ${Object.keys(wsConfig.mimeTypes).join(", ")}`);
+      const res = await drive.files.export({ fileId, mimeType: exportMime }, { responseType: "arraybuffer" });
+      data = res.data;
+    } else {
+      const res = await drive.files.get({ fileId, alt: "media", supportsAllDrives: true }, { responseType: "arraybuffer" });
+      data = res.data;
+    }
+
+    const result = await saveToDisk(data, savePath);
+    return jsonResponse({ downloaded: name, format: exportFormat || (wsConfig ? wsConfig.default : mimeType), path: result.path, size: result.size });
+  } catch (err) { return errorResponse(err.message); }
+});
+
 server.registerTool("gdrive_create_file", {
   description: "Create a new file in Google Drive. Set ocrLanguage to trigger OCR on image/PDF uploads.",
   inputSchema: {
@@ -480,10 +601,11 @@ server.registerTool("gdrive_search_files", {
     modifiedAfter: z.string().optional().describe("ISO date — only files modified after this date"),
     trashed: z.boolean().optional().default(false).describe("Include trashed files (default: false)"),
     maxResults: z.number().optional().default(20).describe("Maximum results (default: 20)"),
+    outputFormat: OUTPUT_FORMAT_SCHEMA,
     account: z.string().optional().describe("Account label (default: active account)"),
   },
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-}, async ({ text, mimeType, modifiedAfter, trashed, maxResults, account }) => {
+}, async ({ text, mimeType, modifiedAfter, trashed, maxResults, outputFormat, account }) => {
   try {
     const { drive } = await getClients(account);
     const parts = [`fullText contains '${text.replace(/'/g, "\\'")}'`];
@@ -495,7 +617,7 @@ server.registerTool("gdrive_search_files", {
       fields: `files(${LIST_FIELDS},description)`,
       supportsAllDrives: true, includeItemsFromAllDrives: true,
     });
-    return jsonResponse({ files: res.data.files || [], resultCount: (res.data.files || []).length });
+    return formatOutput({ files: res.data.files || [], resultCount: (res.data.files || []).length }, outputFormat);
   } catch (err) { return errorResponse(err.message); }
 });
 
@@ -526,10 +648,11 @@ server.registerTool("gdrive_list_folder", {
     pageSize: z.number().optional().default(50).describe("Results per page (max 100, default: 50)"),
     pageToken: z.string().optional().describe("Token for next page"),
     orderBy: z.string().optional().default("folder,name").describe("Sort order (default: folders first, then by name)"),
+    outputFormat: OUTPUT_FORMAT_SCHEMA,
     account: z.string().optional().describe("Account label (default: active account)"),
   },
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-}, async ({ folderId, pageSize, pageToken, orderBy, account }) => {
+}, async ({ folderId, pageSize, pageToken, orderBy, outputFormat, account }) => {
   try {
     const { drive } = await getClients(account);
     const res = await drive.files.list({
@@ -538,7 +661,7 @@ server.registerTool("gdrive_list_folder", {
       orderBy: orderBy || "folder,name", fields: `nextPageToken,files(${LIST_FIELDS})`,
       supportsAllDrives: true, includeItemsFromAllDrives: true,
     });
-    return jsonResponse({ files: res.data.files || [], nextPageToken: res.data.nextPageToken || null });
+    return formatOutput({ files: res.data.files || [], nextPageToken: res.data.nextPageToken || null }, outputFormat);
   } catch (err) { return errorResponse(err.message); }
 });
 
@@ -595,7 +718,7 @@ server.registerTool("gdrive_untrash_file", {
 });
 
 server.registerTool("gdrive_empty_trash", {
-  description: "Permanently delete ALL files in trash. Irreversible.",
+  description: "Permanently delete ALL files in trash. Irreversible. Note: Google returns success before files are fully purged (eventual consistency — files may still appear briefly in trash listings).",
   inputSchema: {
     account: z.string().optional().describe("Account label (default: active account)"),
   },
@@ -613,10 +736,11 @@ server.registerTool("gdrive_list_trash", {
   inputSchema: {
     pageSize: z.number().optional().default(20).describe("Results per page (max 100, default: 20)"),
     pageToken: z.string().optional().describe("Token for next page"),
+    outputFormat: OUTPUT_FORMAT_SCHEMA,
     account: z.string().optional().describe("Account label (default: active account)"),
   },
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-}, async ({ pageSize, pageToken, account }) => {
+}, async ({ pageSize, pageToken, outputFormat, account }) => {
   try {
     const { drive } = await getClients(account);
     const res = await drive.files.list({
@@ -624,7 +748,7 @@ server.registerTool("gdrive_list_trash", {
       pageToken: pageToken || undefined, fields: `nextPageToken,files(${LIST_FIELDS},trashedTime)`, orderBy: "modifiedTime desc",
       supportsAllDrives: true, includeItemsFromAllDrives: true,
     });
-    return jsonResponse({ files: res.data.files || [], nextPageToken: res.data.nextPageToken || null });
+    return formatOutput({ files: res.data.files || [], nextPageToken: res.data.nextPageToken || null }, outputFormat);
   } catch (err) { return errorResponse(err.message); }
 });
 
@@ -661,16 +785,17 @@ server.registerTool("gdrive_list_permissions", {
   description: "List all permissions (sharing) on a file or folder.",
   inputSchema: {
     fileId: z.string().describe("File or folder ID"),
+    outputFormat: OUTPUT_FORMAT_SCHEMA,
     account: z.string().optional().describe("Account label (default: active account)"),
   },
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-}, async ({ fileId, account }) => {
+}, async ({ fileId, outputFormat, account }) => {
   try {
     const { drive } = await getClients(account);
     const res = await drive.permissions.list({
       fileId, fields: "permissions(id,role,type,emailAddress,domain,displayName)", supportsAllDrives: true,
     });
-    return jsonResponse({ permissions: res.data.permissions || [] });
+    return formatOutput({ permissions: res.data.permissions || [] }, outputFormat);
   } catch (err) { return errorResponse(err.message); }
 });
 
@@ -710,7 +835,7 @@ server.registerTool("gdrive_remove_permission", {
 });
 
 server.registerTool("gdrive_transfer_ownership", {
-  description: "Transfer ownership of a file to another user.",
+  description: "Transfer ownership of a file to another user. Note: cross-organization transfers (e.g., personal to Workspace) are blocked by Google.",
   inputSchema: {
     fileId: z.string().describe("File ID to transfer"),
     email: z.string().describe("New owner's email address"),
@@ -733,17 +858,18 @@ server.registerTool("gdrive_transfer_ownership", {
 server.registerTool("gdrive_list_labels", {
   description: "List available Drive labels that can be applied to files.",
   inputSchema: {
+    outputFormat: OUTPUT_FORMAT_SCHEMA,
     account: z.string().optional().describe("Account label (default: active account)"),
   },
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-}, async ({ account }) => {
+}, async ({ outputFormat, account }) => {
   try {
     const config = await loadConfig();
     const label = account || config.active || "primary";
     const auth = await authorizeAccount(label);
     const labels = google.drivelabels({ version: "v2", auth });
     const res = await labels.labels.list({ publishedOnly: true, view: "LABEL_VIEW_FULL" });
-    return jsonResponse({ labels: res.data.labels || [] });
+    return formatOutput({ labels: res.data.labels || [] }, outputFormat);
   } catch (err) { return errorResponse(err.message); }
 });
 
@@ -751,14 +877,15 @@ server.registerTool("gdrive_list_file_labels", {
   description: "List labels currently applied to a file.",
   inputSchema: {
     fileId: z.string().describe("File ID"),
+    outputFormat: OUTPUT_FORMAT_SCHEMA,
     account: z.string().optional().describe("Account label (default: active account)"),
   },
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-}, async ({ fileId, account }) => {
+}, async ({ fileId, outputFormat, account }) => {
   try {
     const { drive } = await getClients(account);
     const res = await drive.files.listLabels({ fileId });
-    return jsonResponse({ labels: res.data.labels || [] });
+    return formatOutput({ labels: res.data.labels || [] }, outputFormat);
   } catch (err) { return errorResponse(err.message); }
 });
 
@@ -791,21 +918,22 @@ server.registerTool("gdrive_set_file_labels", {
 // ═══ DOCS TOOLS ══════════════════════════════════════════════════════════════
 
 server.registerTool("gdrive_export_doc", {
-  description: "Export a Google Doc. Default: markdown. Also: html, text, docx, pdf.",
+  description: "Export a Google Doc. Default: markdown. Also: html, text, docx, pdf. Use savePath to save binary formats to disk.",
   inputSchema: {
     fileId: z.string().describe("Google Doc file ID"),
     format: z.enum(["markdown", "html", "text", "docx", "pdf"]).optional().default("markdown").describe("Export format (default: markdown)"),
+    savePath: z.string().optional().describe("Local file path to save binary exports (docx/pdf). If omitted, returns base64."),
     account: z.string().optional().describe("Account label (default: active account)"),
   },
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-}, async ({ fileId, format, account }) => {
+}, async ({ fileId, format, savePath, account }) => {
   try {
     const { drive } = await getClients(account);
     const mimeMap = { markdown: "text/html", html: "text/html", text: "text/plain", docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document", pdf: "application/pdf" };
     const isBinary = ["docx", "pdf"].includes(format);
     const res = await drive.files.export({ fileId, mimeType: mimeMap[format] }, { responseType: isBinary ? "arraybuffer" : "text" });
     if (format === "markdown") return textResponse(turndown.turndown(res.data));
-    if (isBinary) return binaryResponse(res.data, format.toUpperCase());
+    if (isBinary) return handleBinaryExport(res.data, format, savePath);
     return textResponse(res.data);
   } catch (err) { return errorResponse(err.message); }
 });
@@ -875,20 +1003,21 @@ server.registerTool("gdrive_create_sheet", {
 });
 
 server.registerTool("gdrive_export_sheet", {
-  description: "Export a Google Sheet to CSV, JSON, or XLSX.",
+  description: "Export a Google Sheet to CSV, JSON, or XLSX. Use savePath to save XLSX to disk.",
   inputSchema: {
     fileId: z.string().describe("Google Sheet file ID"),
     format: z.enum(["csv", "json", "xlsx"]).optional().default("csv").describe("Export format (default: csv)"),
     sheetName: z.string().optional().describe("Specific sheet/tab name (default: first sheet). Only for csv/json."),
+    savePath: z.string().optional().describe("Local file path to save XLSX export. If omitted, returns base64."),
     account: z.string().optional().describe("Account label (default: active account)"),
   },
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-}, async ({ fileId, format, sheetName, account }) => {
+}, async ({ fileId, format, sheetName, savePath, account }) => {
   try {
     const { sheets, drive } = await getClients(account);
     if (format === "xlsx") {
       const res = await drive.files.export({ fileId, mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" }, { responseType: "arraybuffer" });
-      return binaryResponse(res.data, "XLSX");
+      return handleBinaryExport(res.data, "xlsx", savePath);
     }
     let rangeParam = sheetName;
     if (!rangeParam) {
@@ -916,14 +1045,15 @@ server.registerTool("gdrive_list_sheets", {
   description: "List all sheets/tabs in a Google Spreadsheet.",
   inputSchema: {
     fileId: z.string().describe("Google Sheet file ID"),
+    outputFormat: OUTPUT_FORMAT_SCHEMA,
     account: z.string().optional().describe("Account label (default: active account)"),
   },
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-}, async ({ fileId, account }) => {
+}, async ({ fileId, outputFormat, account }) => {
   try {
     const { sheets } = await getClients(account);
     const res = await sheets.spreadsheets.get({ spreadsheetId: fileId, fields: "sheets.properties" });
-    return jsonResponse({ sheets: (res.data.sheets || []).map(s => ({ title: s.properties.title, sheetId: s.properties.sheetId, index: s.properties.index, rowCount: s.properties.gridProperties?.rowCount, columnCount: s.properties.gridProperties?.columnCount })) });
+    return formatOutput({ sheets: (res.data.sheets || []).map(s => ({ title: s.properties.title, sheetId: s.properties.sheetId, index: s.properties.index, rowCount: s.properties.gridProperties?.rowCount, columnCount: s.properties.gridProperties?.columnCount })) }, outputFormat);
   } catch (err) { return errorResponse(err.message); }
 });
 
@@ -933,15 +1063,16 @@ server.registerTool("gdrive_read_sheet_range", {
     fileId: z.string().describe("Google Sheet file ID"),
     range: z.string().describe("A1 notation range (e.g., 'Sheet1!A1:D10', 'Sales!A:A')"),
     valueRender: z.enum(["formatted", "unformatted", "formula"]).optional().default("formatted").describe("How to render values (default: formatted)"),
+    outputFormat: OUTPUT_FORMAT_SCHEMA,
     account: z.string().optional().describe("Account label (default: active account)"),
   },
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-}, async ({ fileId, range, valueRender, account }) => {
+}, async ({ fileId, range, valueRender, outputFormat, account }) => {
   try {
     const { sheets } = await getClients(account);
     const renderMap = { formatted: "FORMATTED_VALUE", unformatted: "UNFORMATTED_VALUE", formula: "FORMULA" };
     const res = await sheets.spreadsheets.values.get({ spreadsheetId: fileId, range, valueRenderOption: renderMap[valueRender] || "FORMATTED_VALUE" });
-    return jsonResponse({ range: res.data.range, values: res.data.values || [] });
+    return formatOutput({ range: res.data.range, values: res.data.values || [] }, outputFormat);
   } catch (err) { return errorResponse(err.message); }
 });
 
@@ -987,20 +1118,21 @@ server.registerTool("gdrive_create_slides", {
 });
 
 server.registerTool("gdrive_export_slides", {
-  description: "Export Google Slides to text, PDF, or PPTX.",
+  description: "Export Google Slides to text, PDF, or PPTX. Use savePath to save binary formats to disk.",
   inputSchema: {
     fileId: z.string().describe("Google Slides file ID"),
     format: z.enum(["text", "pdf", "pptx"]).optional().default("text").describe("Export format (default: text)"),
+    savePath: z.string().optional().describe("Local file path to save binary exports (pdf/pptx). If omitted, returns base64."),
     account: z.string().optional().describe("Account label (default: active account)"),
   },
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-}, async ({ fileId, format, account }) => {
+}, async ({ fileId, format, savePath, account }) => {
   try {
     const { drive } = await getClients(account);
     const mimeMap = { text: "text/plain", pdf: "application/pdf", pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation" };
     const isBinary = ["pdf", "pptx"].includes(format);
     const res = await drive.files.export({ fileId, mimeType: mimeMap[format] }, { responseType: isBinary ? "arraybuffer" : "text" });
-    if (isBinary) return binaryResponse(res.data, format.toUpperCase());
+    if (isBinary) return handleBinaryExport(res.data, format, savePath);
     return textResponse(res.data);
   } catch (err) { return errorResponse(err.message); }
 });
@@ -1010,17 +1142,18 @@ server.registerTool("gdrive_get_slide_thumbnail", {
   inputSchema: {
     fileId: z.string().describe("Google Slides file ID"),
     slideIndex: z.number().optional().default(0).describe("Slide index, 0-based (default: first slide)"),
+    outputFormat: OUTPUT_FORMAT_SCHEMA,
     account: z.string().optional().describe("Account label (default: active account)"),
   },
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-}, async ({ fileId, slideIndex, account }) => {
+}, async ({ fileId, slideIndex, outputFormat, account }) => {
   try {
     const { slides } = await getClients(account);
     const pres = await slides.presentations.get({ presentationId: fileId, fields: "slides.objectId" });
     const pages = pres.data.slides || [];
     if (slideIndex >= pages.length) return errorResponse(`Slide index ${slideIndex} out of range (${pages.length} slides)`);
     const thumb = await slides.presentations.pages.getThumbnail({ presentationId: fileId, pageObjectId: pages[slideIndex].objectId, "thumbnailProperties.mimeType": "PNG" });
-    return jsonResponse({ slideIndex, pageId: pages[slideIndex].objectId, thumbnailUrl: thumb.data.contentUrl, width: thumb.data.width, height: thumb.data.height });
+    return formatOutput({ slideIndex, pageId: pages[slideIndex].objectId, thumbnailUrl: thumb.data.contentUrl, width: thumb.data.width, height: thumb.data.height }, outputFormat);
   } catch (err) { return errorResponse(err.message); }
 });