# mcp-google-gdrive

An [MCP](https://modelcontextprotocol.io/) server for Google Drive, Docs, Sheets, and Slides. Lets AI assistants manage files, folders, permissions, labels, and trash with full read/write access across multiple Google accounts. Includes automatic Workspace format conversion (Docs to Markdown, Sheets to CSV/JSON, Slides to text).

## Tools

### Account Management

| Tool | Description |
|------|-------------|
| `gdrive_list_accounts` | List all configured Google accounts with labels and emails |
| `gdrive_switch_account` | Set the active account for subsequent calls |
| `gdrive_add_account` | Generate an authorization URL to add a new Google account |

### Files

| Tool | Description |
|------|-------------|
| `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 |
| `gdrive_move_file` | Move a file to a different folder |
| `gdrive_search_files` | Full-text search across file names and content |

### Folders

| Tool | Description |
|------|-------------|
| `gdrive_create_folder` | Create a new folder |
| `gdrive_list_folder` | List contents of a specific folder |
| `gdrive_delete_folder` | Delete a folder (trash or permanent) |

### Trash

| Tool | Description |
|------|-------------|
| `gdrive_trash_file` | Move a file or folder to trash |
| `gdrive_untrash_file` | Restore a file or folder from trash |
| `gdrive_empty_trash` | Permanently delete all trashed files (irreversible) |
| `gdrive_list_trash` | List files currently in trash |

### Permissions

| Tool | Description |
|------|-------------|
| `gdrive_share_file` | Share a file with a user, group, domain, or anyone |
| `gdrive_list_permissions` | List all permissions on a file or folder |
| `gdrive_update_permission` | Update a permission's role |
| `gdrive_remove_permission` | Remove a permission (unshare) |
| `gdrive_transfer_ownership` | Transfer file ownership to another user |

### Labels

| Tool | Description |
|------|-------------|
| `gdrive_list_labels` | List available Drive labels |
| `gdrive_list_file_labels` | List labels applied to a file |
| `gdrive_set_file_labels` | Add, update, or remove labels on a file |

### Google Docs

| Tool | Description |
|------|-------------|
| `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 |

### Google Sheets

| Tool | Description |
|------|-------------|
| `gdrive_create_sheet` | Create a new spreadsheet with named tabs |
| `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 |

### Google Slides

| Tool | Description |
|------|-------------|
| `gdrive_create_slides` | Create a new presentation |
| `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+
- A Google Cloud project with these APIs enabled:
  - Google Drive API
  - Google Docs API
  - Google Sheets API
  - Google Slides API
- OAuth2 desktop application credentials

## Setup

1. Create a project in the [Google Cloud Console](https://console.cloud.google.com/) and enable the Drive, Docs, Sheets, and Slides APIs
2. Create OAuth2 credentials (Application type: Desktop app) and download the JSON file
3. Save the credentials file:

```bash
mkdir -p ~/.config/mcp-google-gdrive
cp ~/Downloads/client_secret_*.json ~/.config/mcp-google-gdrive/credentials.json
chmod 600 ~/.config/mcp-google-gdrive/credentials.json
```

4. Run the one-time authorization flow:

```bash
npx mcp-google-gdrive --auth primary
```

This prints a URL for Google consent. After granting access, paste the authorization code back into the terminal.

### Multi-Account Setup

Add additional accounts with unique labels:

```bash
npx mcp-google-gdrive --auth work
npx mcp-google-gdrive --auth personal
```

Each account gets its own token file at `~/.config/mcp-google-gdrive/tokens/{label}.json`. Use the `account` parameter on any tool to specify which account to use, or call `gdrive_switch_account` to change the default.

## Configuration

### Gemini CLI

Add to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "google-gdrive": {
      "command": "npx",
      "args": ["-y", "mcp-google-gdrive"]
    }
  }
}
```

### watsonx Orchestrate

```bash
orchestrate toolkits import --kind mcp \
  --name google-gdrive \
  --description "Google Drive, Docs, Sheets, Slides" \
  --command "npx -y mcp-google-gdrive" \
  --tools "*"
```

### Claude Code

```bash
claude mcp add -s user google-gdrive -- npx -y mcp-google-gdrive
```

### VS Code / Cursor

Add to `.vscode/mcp.json` in your workspace:

```json
{
  "mcpServers": {
    "google-gdrive": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-gdrive"]
    }
  }
}
```

## Authentication

The server uses OAuth2 for Google Drive access. Credentials are stored locally:

- `~/.config/mcp-google-gdrive/credentials.json` — OAuth2 client (shared across accounts)
- `~/.config/mcp-google-gdrive/tokens/{label}.json` — Per-account tokens (chmod 600)
- `~/.config/mcp-google-gdrive/config.json` — Active account and account registry

Access tokens expire after one hour and are refreshed automatically using stored refresh tokens. Token refresh is transparent and requires no user interaction.

### Migrating from v0.x

If upgrading from a single-account v0.x installation, the server automatically migrates your existing `token.json` to `tokens/primary.json` on first start.

## Related MCP Servers

- [mcp-redhat-account](https://github.com/sleepytimeshon/mcp-redhat-account) - Red Hat account management
- [mcp-redhat-knowledge](https://github.com/sleepytimeshon/mcp-redhat-knowledge) - Red Hat Knowledge Base search
- [mcp-redhat-manpage](https://github.com/sleepytimeshon/mcp-redhat-manpage) - RHEL man pages
- [mcp-redhat-subscription](https://github.com/sleepytimeshon/mcp-redhat-subscription) - Subscription management
- [mcp-redhat-support](https://github.com/sleepytimeshon/mcp-redhat-support) - Support case management

## License

MIT