gdrive-org

AI-Powered Digital Minimalist Google Drive CLI & MCP Server

gdrive-org helps you declutter, organize, and regain control over your Google Drive. It features AI-assisted semantic deduplication, three-tier duplication removal, macOS Drive File Stream cache monitoring, config-driven folder cleaning, and a native Model Context Protocol (MCP) server for AI agents (Claude Desktop, Cursor, Antigravity, etc.).

Features

• 🧹 Clean Empty Folders: Identify and prune empty folder hierarchies recursively.

• 📦 Storage & Cache Analysis: Inspect cloud quota usage and macOS local DriveFS cache footprint.

• 🔍 File Audit: Detect oversized items, root directory clutter, orphaned files, and shortcuts.

• 👯 Byte-Exact Deduplication: Safely identify duplicate files by MD5 hash and batch-trash duplicates while preserving the oldest original.

• 🧠 Smart AI Deduplication: Cluster semantically similar documents with Gemini AI and consolidate them into a Single Source of Truth doc.

• 📁 Config-Driven Folder Cleaner: Classify, flatten, and clean specific folders according to customized YAML rules.

• 🤖 Native MCP Server: Expose Drive management tools directly to LLMs and agentic IDEs via Model Context Protocol.

• 🍏 macOS Sync Health: Monitor local Google Drive for Desktop sync health and cache size.

• 🛡️ Safe by Default: All destructive operations default to dry-run mode, respect a 30-day Drive Trash recovery window, and support resuming interrupted batch jobs.

Installation

Standalone CLI (Recommended)

Using uv or pipx:

uv tool install gdrive-org
# or
pipx install gdrive-org

Or run directly without permanent installation via uvx:

uvx gdrive-org --help

From Source (Development)

git clone https://github.com/yourusername/google-drive-organization.git
cd google-drive-organization
python -m venv .venv
source .venv/bin/activate
pip install -e .

Configuration & Credentials

1. Google Drive API (OAuth 2.0)

1. Open the Google Cloud Console.

2. Create a new project (e.g. gdrive-org).

3. Under APIs & Services > Library, enable the Google Drive API.

4. Under APIs & Services > Credentials, click Create Credentials > OAuth client ID.

5. Select Desktop app as the application type.

6. Download the resulting credentials JSON file.

7. Save it to ~/.config/gdrive-org/credentials.json (or place it in your local directory as credentials.json):

   mkdir -p ~/.config/gdrive-org
   cp /path/to/downloaded-credentials.json ~/.config/gdrive-org/credentials.json

2. Gemini API Key (for Smart Dedupe & Cluster Merge)

1. Obtain an API key from Google AI Studio.

2. Add it to ~/.config/gdrive-org/.env:

   GOOGLE_API_KEY=your_gemini_api_key_here

   (Alternatively, export GOOGLE_API_KEY in your shell environment).

CLI Usage

Authentication

Test and authorize your Google Drive credentials (opens a browser window for first-time login):

gdrive-org auth

Storage & Sync Audit

gdrive-org storage                     # View cloud quota and local cache footprint
gdrive-org audit --min-size 50         # List items >= 50MB and audit root clutter
gdrive-org sync-health                 # Check macOS Drive File Stream cache and health
gdrive-org explain-sync                # Guide for Stream vs Mirror sync modes

Deduplication

Find exact byte-identical duplicates (dry-run):

gdrive-org dedupe

Execute deduplication (moves duplicates to Trash, keeps oldest original):

gdrive-org dedupe --no-dry-run

Exclude specific directories:

gdrive-org dedupe --exclude-folder "Archive" --exclude-folder "Backups"

Smart AI Deduplication

Scan for semantic duplicates and manage proposed merge clusters:

gdrive-org smart-dedupe                # Cluster related docs and propose merges
gdrive-org merge approve <cluster-id>  # Finalize merged Google Doc & trash originals
gdrive-org merge reject <cluster-id>   # Discard proposed merge

Folder Cleaning & Empty Folder Pruning

Remove empty directories:

gdrive-org clean-empty                 # Dry-run
gdrive-org clean-empty --no-dry-run    # Delete empty folders

Clean a specific folder using a custom YAML rule set:

gdrive-org clean-folder <folder-id> --config /path/to/rules.yaml
gdrive-org clean-folder <folder-id> --config /path/to/rules.yaml --no-dry-run

Archiving & Recovery

Archive unorganized old root files to Archive/<Year>:

gdrive-org archive --months 6          # Dry-run files unaccessed for 6 months
gdrive-org archive --months 6 --no-dry-run

Resume interrupted batch operations:

gdrive-org resume

Model Context Protocol (MCP) Integration

gdrive-org can run as an MCP server, allowing agents like Claude Desktop, Cursor, or Antigravity to safely analyze, deduplicate, and organize your Google Drive.

Start the Server Directly

gdrive-org mcp
# or with uvx:
uvx gdrive-org mcp

Client Configuration

Add gdrive-org to your MCP client config (e.g. claude_desktop_config.json, Antigravity mcp_config.json, or Cursor):

{
  "mcpServers": {
    "gdrive-org": {
      "command": "uvx",
      "args": ["gdrive-org", "mcp"]
    }
  }
}

(During local development before PyPI installation, point command to your local .venv/bin/gdrive-org and args to ["mcp"]).

Available MCP Tools

Safety Guidelines

1. Dry-Run by Default: All bulk modifications and deletions run in dry-run mode until --no-dry-run or an explicit execute action is triggered.

2. 30-Day Trash Recovery: Deletions move files to Google Drive's native Trash. Files can be restored within 30 days.

3. Audit Trail: Every destructive action is logged to enable state recovery and rollback analysis.

4. Local Cache Safety: Never manually delete files inside ~/Library/Application Support/Google/DriveFS. Use gdrive-org sync-health and Google Drive preferences to clear streaming cache safely.

License

MIT License — see LICENSE for details.