google-drive-files-mcp 0.3.0__tar.gz

google_drive_files_mcp-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Test
+        run: pytest -v

google_drive_files_mcp-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/google-drive-files-mcp/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

google_drive_files_mcp-0.3.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual envs
+.venv/
+venv/
+env/
+.env
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Credentials — NEVER commit
+credentials.json
+token.json
+client_secret*.json
+*.pem
+*.key

google_drive_files_mcp-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zayan Khan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

google_drive_files_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: google-drive-files-mcp
+Version: 0.3.0
+Summary: A minimal MCP server and CLI for Google Drive file management (move, upload, organize) and Google Sheets editing.
+Project-URL: Homepage, https://github.com/zayansalman/google-drive-files-mcp
+Project-URL: Repository, https://github.com/zayansalman/google-drive-files-mcp
+Project-URL: Issues, https://github.com/zayansalman/google-drive-files-mcp/issues
+Author: Zayan Khan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anthropic,claude,files,google-drive,google-sheets,mcp,model-context-protocol,move,spreadsheet,upload
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: google-api-python-client>=2.100.0
+Requires-Dist: google-auth-httplib2>=0.2.0
+Requires-Dist: google-auth-oauthlib>=1.0.0
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# google-drive-files-mcp
+
+<!-- mcp-name: io.github.zayansalman/google-drive-files-mcp -->
+
+A focused [Model Context Protocol](https://modelcontextprotocol.io) server (and standalone CLI) for **Google Drive file management** (move, upload, organize) **and Google Sheets editing** (update cells, append rows, edit tabs, format). Fourteen granular, single-purpose tools — each one an explicit operation, with writes returning before/after so nothing is silently overwritten.
+
+Built because the hosted Google Drive connectors can search, read, and **copy** files, but cannot **move** them (`copy` duplicates a file with a new ID rather than relocating it), cannot reliably **upload a real binary** (their inline-content API needs the bytes embedded as base64, which breaks for large/binary files), and cannot **edit spreadsheet contents**. This server adds a true move, a resumable upload from a local path, folder creation, and a full set of Google Sheets value/structure/format edits — for any MCP client (Claude Code, Claude Desktop, Cursor, Cline, etc.).
+
+## Tools
+
+### Drive — files & folders
+- `drive_search(query, only_folders=False, max_results=20)` — find files/folders (and their IDs).
+- `drive_create_folder(name, parent=None)` — create a folder (`parent` accepts an ID, URL, `root`, or an unambiguous folder name).
+- `drive_move(file, dest_folder, keep_existing_parents=False)` — *true move* (removed from its current folder); `keep_existing_parents=True` adds without removing.
+- `drive_upload_file(local_path, parent=None, name=None, mime_type=None)` — upload a local file (any type, incl. large binaries) via a **resumable media upload**. Stored as-is (no Google-format conversion).
+
+### Google Sheets — read, edit, structure, format
+- `sheets_get_info(spreadsheet)` — list tabs + sizes (call first to learn tab names).
+- `sheets_read(spreadsheet, range_a1, render_option="FORMATTED_VALUE")` — read a range (`FORMULA`/`UNFORMATTED_VALUE` available).
+- `sheets_write(spreadsheet, range_a1, values, value_input_option="USER_ENTERED")` — overwrite a range; returns `before`. `USER_ENTERED` parses numbers and makes `=SUM(..)` a formula; `RAW` writes literally.
+- `sheets_append(spreadsheet, range_a1, values, ...)` — append rows after a table.
+- `sheets_clear(spreadsheet, range_a1)` — clear values (keeps formatting); returns `before`.
+- `sheets_batch_write(spreadsheet, updates, ...)` — write many ranges atomically.
+- `sheets_add_tab` / `sheets_rename_tab` / `sheets_delete_tab` — manage tabs (delete is destructive).
+- `sheets_format(spreadsheet, range_a1, number_format=None, bold=None, background=None)` — number pattern / bold / `#RRGGBB` background.
+
+No rename/copy/trash/delete of *files* (copy already exists in the hosted Drive connector); destructive Sheets ops (`sheets_clear`, `sheets_delete_tab`) are their own explicit tools so you control exactly when they run.
+
+## Scope warning (read this)
+
+Moving an existing arbitrary file requires the **full `drive` scope** — read/write/delete on **all** your Drive files. There is no narrower scope that can change a file's parents (`drive.file` only covers files the app itself created). This tool is therefore far more powerful than a read-only connector. Treat its cached token like a password (stored `0600`), and prefer an isolated OAuth client/token rather than sharing one with read-only tools.
+
+## Install
+
+```bash
+pip install google-drive-files-mcp
+# or: uv tool install google-drive-files-mcp
+```
+
+## One-time setup (~10 min)
+
+1. [Google Cloud Console](https://console.cloud.google.com/) → create/pick a project.
+2. Enable the **Drive API** ([library link](https://console.cloud.google.com/apis/library/drive.googleapis.com)) and, for the Sheets tools, the **Sheets API** ([library link](https://console.cloud.google.com/apis/library/sheets.googleapis.com)). (The full `drive` scope already authorizes the Sheets API — no extra consent, just enable the API.)
+3. OAuth consent screen → **Internal** (Workspace; no verification needed even for the restricted full-drive scope) or **External** + add yourself as a test user (personal Gmail).
+4. Credentials → **OAuth client ID** → **Desktop app** → download JSON.
+5. `google-drive-files-mcp setup --import-credentials ~/Downloads/client_secret_*.json` → consent in the browser.
+
+Verify:
+```bash
+google-drive-files-mcp status
+google-drive-files-mcp search "Reports" --folders
+```
+
+## Claude Code
+
+```bash
+claude mcp add --scope user google-drive-files google-drive-files-mcp -- serve
+```
+
+> Find my "Q2 Report" doc and move it into the "2026 Reports" folder.
+
+## Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "google-drive-files": { "command": "google-drive-files-mcp", "args": ["serve"] }
+  }
+}
+```
+
+## CLI
+
+```bash
+google-drive-files-mcp search "budget"                 # find a file + its ID
+google-drive-files-mcp search "Reports" --folders      # find destination folders
+google-drive-files-mcp mkdir "2026 Reports"            # create a folder
+google-drive-files-mcp move <file-url-or-id> "2026 Reports"   # move into it (by folder name)
+google-drive-files-mcp move <file-url-or-id> root      # move back to My Drive root
+google-drive-files-mcp upload ~/Downloads/report.zip --parent "2026 Reports"   # upload a local file
+
+# Google Sheets
+google-drive-files-mcp sheet-info  <sheet-url-or-id>                 # list tabs + sizes
+google-drive-files-mcp sheet-read  <sheet-url-or-id> "Sheet1!A1:D10" # read a range
+google-drive-files-mcp sheet-write <sheet-url-or-id> "Sheet1!B2:B4" '[[100],[200],[300]]'   # set numbers
+google-drive-files-mcp sheet-format <sheet-url-or-id> "Sheet1!B2:B4" --number-format '#,##0.00' --bold
+```
+
+`drive_move` returns the before/after parents so the move is auditable:
+```json
+{ "id": "1Abc…", "name": "Q2 Report", "moved_from": ["0OldFolderId"], "moved_to": "1NewFolderId", "parents_now": ["1NewFolderId"], "web_view_link": "https://docs.google.com/…" }
+```
+
+## Configuration
+
+| Variable | Default | What |
+|---|---|---|
+| `GDRIVE_FILES_MCP_CREDENTIALS` | `~/.config/google-drive-files-mcp/credentials.json` | OAuth client secret |
+| `GDRIVE_FILES_MCP_TOKEN` | `~/.config/google-drive-files-mcp/token.json` | Cached refresh token |
+| `GDRIVE_FILES_MCP_SCOPES` | `https://www.googleapis.com/auth/drive` | OAuth scopes (comma-separated) |
+
+## Safety notes
+
+- **True move removes the file from its current folder.** Drive items can have multiple parents; `keep_existing_parents=True` adds without removing.
+- **Folder-name destinations must be unambiguous.** If two folders share a name, `drive_move` refuses and lists the candidates so you can pass an explicit ID.
+- **The before/after parents are returned** on every move so an agent (or you) can verify the result.
+
+## Troubleshooting
+
+**`HttpError 403: Google Drive API has not been used in project … or it is disabled`**
+Enable the Drive API on the project that owns your OAuth client: [console.cloud.google.com/apis/library/drive.googleapis.com](https://console.cloud.google.com/apis/library/drive.googleapis.com) → **Enable**, then wait ~1 min and retry. (This is the single most common first-run error.)
+
+**`multiple folders named '…'; pass the folder ID/URL instead`**
+Two or more of your folders share that name, so a name is ambiguous. Run `google-drive-files-mcp search "<name>" --folders` to get the IDs and pass the exact one.
+
+**`no folder named '…' found`**
+Create it first (`google-drive-files-mcp mkdir "<name>"`) or pass a folder ID/URL/`root`.
+
+**`HttpError 403: insufficientFilePermissions` when moving**
+Either the token lacks the full `drive` scope — re-authorize with `google-drive-files-mcp setup --reauth` — or you don't have edit rights on the file/destination (you can't move a file someone else owns unless they've granted you edit access).
+
+**`No valid Google token` from Claude Desktop / cron**
+The first consent needs a browser. Run `google-drive-files-mcp setup` once in a terminal; later headless runs reuse and auto-refresh the cached token.
+
+**A move "removed" a file from a shared folder unexpectedly**
+A true move removes the item from its current parent(s). If you meant to *also* keep it where it was, use `keep_existing_parents=true` (CLI `--keep`).
+
+## Use it from other clients (Cursor, Cline, Continue, …)
+
+Any stdio MCP client works — see [docs/other-clients.md](docs/other-clients.md).
+
+## Authentication — bring your own Google OAuth client
+
+There are **no API keys and no shipped secrets**. The server authenticates to *your* Google account with an OAuth client *you* create, and caches a refresh token locally. The author has zero access to your data.
+
+- **Why your own client?** Google's restricted scopes (here, the full `drive` scope) can't be redistributed in a shared app, and an unverified shared app is capped at 100 users. "Bring your own OAuth client" is the standard pattern for personal-data MCP servers.
+- **What you need:** a free Google Cloud project, the Drive API enabled, an OAuth consent screen, and a Desktop OAuth client. Full walkthrough → [docs/setup-google-oauth.md](docs/setup-google-oauth.md).
+- **Where your token lives:** `~/.config/google-drive-files-mcp/token.json` (mode `0600`). Delete it to revoke locally; revoke fully at [myaccount.google.com/permissions](https://myaccount.google.com/permissions).
+- **No hosted/SaaS option** — everything runs locally; your Drive data never touches a third-party server.
+
+## More guides
+
+- [docs/setup-google-oauth.md](docs/setup-google-oauth.md) — full OAuth walkthrough (full-`drive` scope) + common errors
+- [docs/claude-code.md](docs/claude-code.md) · [docs/claude-desktop.md](docs/claude-desktop.md) · [docs/other-clients.md](docs/other-clients.md)
+- [examples/](examples/) — e.g. file a document into a `YYYY-MM` folder
+
+## Related tools
+
+Part of a small family of focused, local MCP servers for Google Workspace data the hosted connectors don't expose:
+
+- **[gmail-attachments-mcp](https://github.com/zayansalman/gmail-attachments-mcp)** — download Gmail attachment bytes to disk
+- **[google-drive-comments-mcp](https://github.com/zayansalman/google-drive-comments-mcp)** — read comment threads on Docs/Sheets/Slides
+- **google-drive-files-mcp** — move/organize Drive files *(this repo)*
+
+They can share one OAuth login or stay isolated — see each repo's setup.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

google_drive_files_mcp-0.3.0/README.md

@@ -0,0 +1,159 @@
+# google-drive-files-mcp
+
+<!-- mcp-name: io.github.zayansalman/google-drive-files-mcp -->
+
+A focused [Model Context Protocol](https://modelcontextprotocol.io) server (and standalone CLI) for **Google Drive file management** (move, upload, organize) **and Google Sheets editing** (update cells, append rows, edit tabs, format). Fourteen granular, single-purpose tools — each one an explicit operation, with writes returning before/after so nothing is silently overwritten.
+
+Built because the hosted Google Drive connectors can search, read, and **copy** files, but cannot **move** them (`copy` duplicates a file with a new ID rather than relocating it), cannot reliably **upload a real binary** (their inline-content API needs the bytes embedded as base64, which breaks for large/binary files), and cannot **edit spreadsheet contents**. This server adds a true move, a resumable upload from a local path, folder creation, and a full set of Google Sheets value/structure/format edits — for any MCP client (Claude Code, Claude Desktop, Cursor, Cline, etc.).
+
+## Tools
+
+### Drive — files & folders
+- `drive_search(query, only_folders=False, max_results=20)` — find files/folders (and their IDs).
+- `drive_create_folder(name, parent=None)` — create a folder (`parent` accepts an ID, URL, `root`, or an unambiguous folder name).
+- `drive_move(file, dest_folder, keep_existing_parents=False)` — *true move* (removed from its current folder); `keep_existing_parents=True` adds without removing.
+- `drive_upload_file(local_path, parent=None, name=None, mime_type=None)` — upload a local file (any type, incl. large binaries) via a **resumable media upload**. Stored as-is (no Google-format conversion).
+
+### Google Sheets — read, edit, structure, format
+- `sheets_get_info(spreadsheet)` — list tabs + sizes (call first to learn tab names).
+- `sheets_read(spreadsheet, range_a1, render_option="FORMATTED_VALUE")` — read a range (`FORMULA`/`UNFORMATTED_VALUE` available).
+- `sheets_write(spreadsheet, range_a1, values, value_input_option="USER_ENTERED")` — overwrite a range; returns `before`. `USER_ENTERED` parses numbers and makes `=SUM(..)` a formula; `RAW` writes literally.
+- `sheets_append(spreadsheet, range_a1, values, ...)` — append rows after a table.
+- `sheets_clear(spreadsheet, range_a1)` — clear values (keeps formatting); returns `before`.
+- `sheets_batch_write(spreadsheet, updates, ...)` — write many ranges atomically.
+- `sheets_add_tab` / `sheets_rename_tab` / `sheets_delete_tab` — manage tabs (delete is destructive).
+- `sheets_format(spreadsheet, range_a1, number_format=None, bold=None, background=None)` — number pattern / bold / `#RRGGBB` background.
+
+No rename/copy/trash/delete of *files* (copy already exists in the hosted Drive connector); destructive Sheets ops (`sheets_clear`, `sheets_delete_tab`) are their own explicit tools so you control exactly when they run.
+
+## Scope warning (read this)
+
+Moving an existing arbitrary file requires the **full `drive` scope** — read/write/delete on **all** your Drive files. There is no narrower scope that can change a file's parents (`drive.file` only covers files the app itself created). This tool is therefore far more powerful than a read-only connector. Treat its cached token like a password (stored `0600`), and prefer an isolated OAuth client/token rather than sharing one with read-only tools.
+
+## Install
+
+```bash
+pip install google-drive-files-mcp
+# or: uv tool install google-drive-files-mcp
+```
+
+## One-time setup (~10 min)
+
+1. [Google Cloud Console](https://console.cloud.google.com/) → create/pick a project.
+2. Enable the **Drive API** ([library link](https://console.cloud.google.com/apis/library/drive.googleapis.com)) and, for the Sheets tools, the **Sheets API** ([library link](https://console.cloud.google.com/apis/library/sheets.googleapis.com)). (The full `drive` scope already authorizes the Sheets API — no extra consent, just enable the API.)
+3. OAuth consent screen → **Internal** (Workspace; no verification needed even for the restricted full-drive scope) or **External** + add yourself as a test user (personal Gmail).
+4. Credentials → **OAuth client ID** → **Desktop app** → download JSON.
+5. `google-drive-files-mcp setup --import-credentials ~/Downloads/client_secret_*.json` → consent in the browser.
+
+Verify:
+```bash
+google-drive-files-mcp status
+google-drive-files-mcp search "Reports" --folders
+```
+
+## Claude Code
+
+```bash
+claude mcp add --scope user google-drive-files google-drive-files-mcp -- serve
+```
+
+> Find my "Q2 Report" doc and move it into the "2026 Reports" folder.
+
+## Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "google-drive-files": { "command": "google-drive-files-mcp", "args": ["serve"] }
+  }
+}
+```
+
+## CLI
+
+```bash
+google-drive-files-mcp search "budget"                 # find a file + its ID
+google-drive-files-mcp search "Reports" --folders      # find destination folders
+google-drive-files-mcp mkdir "2026 Reports"            # create a folder
+google-drive-files-mcp move <file-url-or-id> "2026 Reports"   # move into it (by folder name)
+google-drive-files-mcp move <file-url-or-id> root      # move back to My Drive root
+google-drive-files-mcp upload ~/Downloads/report.zip --parent "2026 Reports"   # upload a local file
+
+# Google Sheets
+google-drive-files-mcp sheet-info  <sheet-url-or-id>                 # list tabs + sizes
+google-drive-files-mcp sheet-read  <sheet-url-or-id> "Sheet1!A1:D10" # read a range
+google-drive-files-mcp sheet-write <sheet-url-or-id> "Sheet1!B2:B4" '[[100],[200],[300]]'   # set numbers
+google-drive-files-mcp sheet-format <sheet-url-or-id> "Sheet1!B2:B4" --number-format '#,##0.00' --bold
+```
+
+`drive_move` returns the before/after parents so the move is auditable:
+```json
+{ "id": "1Abc…", "name": "Q2 Report", "moved_from": ["0OldFolderId"], "moved_to": "1NewFolderId", "parents_now": ["1NewFolderId"], "web_view_link": "https://docs.google.com/…" }
+```
+
+## Configuration
+
+| Variable | Default | What |
+|---|---|---|
+| `GDRIVE_FILES_MCP_CREDENTIALS` | `~/.config/google-drive-files-mcp/credentials.json` | OAuth client secret |
+| `GDRIVE_FILES_MCP_TOKEN` | `~/.config/google-drive-files-mcp/token.json` | Cached refresh token |
+| `GDRIVE_FILES_MCP_SCOPES` | `https://www.googleapis.com/auth/drive` | OAuth scopes (comma-separated) |
+
+## Safety notes
+
+- **True move removes the file from its current folder.** Drive items can have multiple parents; `keep_existing_parents=True` adds without removing.
+- **Folder-name destinations must be unambiguous.** If two folders share a name, `drive_move` refuses and lists the candidates so you can pass an explicit ID.
+- **The before/after parents are returned** on every move so an agent (or you) can verify the result.
+
+## Troubleshooting
+
+**`HttpError 403: Google Drive API has not been used in project … or it is disabled`**
+Enable the Drive API on the project that owns your OAuth client: [console.cloud.google.com/apis/library/drive.googleapis.com](https://console.cloud.google.com/apis/library/drive.googleapis.com) → **Enable**, then wait ~1 min and retry. (This is the single most common first-run error.)
+
+**`multiple folders named '…'; pass the folder ID/URL instead`**
+Two or more of your folders share that name, so a name is ambiguous. Run `google-drive-files-mcp search "<name>" --folders` to get the IDs and pass the exact one.
+
+**`no folder named '…' found`**
+Create it first (`google-drive-files-mcp mkdir "<name>"`) or pass a folder ID/URL/`root`.
+
+**`HttpError 403: insufficientFilePermissions` when moving**
+Either the token lacks the full `drive` scope — re-authorize with `google-drive-files-mcp setup --reauth` — or you don't have edit rights on the file/destination (you can't move a file someone else owns unless they've granted you edit access).
+
+**`No valid Google token` from Claude Desktop / cron**
+The first consent needs a browser. Run `google-drive-files-mcp setup` once in a terminal; later headless runs reuse and auto-refresh the cached token.
+
+**A move "removed" a file from a shared folder unexpectedly**
+A true move removes the item from its current parent(s). If you meant to *also* keep it where it was, use `keep_existing_parents=true` (CLI `--keep`).
+
+## Use it from other clients (Cursor, Cline, Continue, …)
+
+Any stdio MCP client works — see [docs/other-clients.md](docs/other-clients.md).
+
+## Authentication — bring your own Google OAuth client
+
+There are **no API keys and no shipped secrets**. The server authenticates to *your* Google account with an OAuth client *you* create, and caches a refresh token locally. The author has zero access to your data.
+
+- **Why your own client?** Google's restricted scopes (here, the full `drive` scope) can't be redistributed in a shared app, and an unverified shared app is capped at 100 users. "Bring your own OAuth client" is the standard pattern for personal-data MCP servers.
+- **What you need:** a free Google Cloud project, the Drive API enabled, an OAuth consent screen, and a Desktop OAuth client. Full walkthrough → [docs/setup-google-oauth.md](docs/setup-google-oauth.md).
+- **Where your token lives:** `~/.config/google-drive-files-mcp/token.json` (mode `0600`). Delete it to revoke locally; revoke fully at [myaccount.google.com/permissions](https://myaccount.google.com/permissions).
+- **No hosted/SaaS option** — everything runs locally; your Drive data never touches a third-party server.
+
+## More guides
+
+- [docs/setup-google-oauth.md](docs/setup-google-oauth.md) — full OAuth walkthrough (full-`drive` scope) + common errors
+- [docs/claude-code.md](docs/claude-code.md) · [docs/claude-desktop.md](docs/claude-desktop.md) · [docs/other-clients.md](docs/other-clients.md)
+- [examples/](examples/) — e.g. file a document into a `YYYY-MM` folder
+
+## Related tools
+
+Part of a small family of focused, local MCP servers for Google Workspace data the hosted connectors don't expose:
+
+- **[gmail-attachments-mcp](https://github.com/zayansalman/gmail-attachments-mcp)** — download Gmail attachment bytes to disk
+- **[google-drive-comments-mcp](https://github.com/zayansalman/google-drive-comments-mcp)** — read comment threads on Docs/Sheets/Slides
+- **google-drive-files-mcp** — move/organize Drive files *(this repo)*
+
+They can share one OAuth login or stay isolated — see each repo's setup.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

google_drive_files_mcp-0.3.0/docs/claude-code.md

@@ -0,0 +1,23 @@
+# Claude Code integration
+
+After `pip install google-drive-files-mcp` and `google-drive-files-mcp setup`:
+
+```bash
+claude mcp add --scope user google-drive-files google-drive-files-mcp -- serve
+```
+
+Verify:
+```bash
+claude mcp list | grep google-drive-files
+# google-drive-files: google-drive-files-mcp serve - ✓ Connected
+```
+
+In a session:
+> Find my "Q2 Report" doc and move it into the "2026 Reports" folder.
+
+Because this tool can move/relocate files, prefer to let it **search first and show you the matches** before moving — `drive_move` returns the before/after parents so every move is auditable.
+
+## Remove
+```bash
+claude mcp remove google-drive-files
+```

google_drive_files_mcp-0.3.0/docs/claude-desktop.md

@@ -0,0 +1,30 @@
+# Claude Desktop integration
+
+After installing and running `google-drive-files-mcp setup`, edit Claude Desktop's MCP config:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "google-drive-files": {
+      "command": "google-drive-files-mcp",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+If the command isn't on Claude Desktop's `$PATH`, use the absolute path from `which google-drive-files-mcp`.
+
+## Newer Claude Desktop / Cowork builds
+Some builds read MCP config from the unified `~/.claude.json` (shared with Claude Code) rather than `claude_desktop_config.json`. If editing the JSON has no effect after a restart, register via the CLI and relaunch:
+
+```bash
+claude mcp add --scope user google-drive-files google-drive-files-mcp -- serve
+```
+
+## Verify
+> Create a folder called "Archive 2026" and move my oldest "Draft" doc into it.

google_drive_files_mcp-0.3.0/docs/other-clients.md

@@ -0,0 +1,32 @@
+# Other MCP clients
+
+Any stdio-transport MCP client can use `google-drive-files-mcp`:
+
+- **Transport**: stdio
+- **Command**: `google-drive-files-mcp` (or the absolute path)
+- **Args**: `["serve"]`
+- **Env** (optional): `GDRIVE_FILES_MCP_CREDENTIALS`, `GDRIVE_FILES_MCP_TOKEN`, `GDRIVE_FILES_MCP_SCOPES`
+
+## Cursor — `~/.cursor/mcp.json`
+```json
+{
+  "mcpServers": {
+    "google-drive-files": { "command": "google-drive-files-mcp", "args": ["serve"] }
+  }
+}
+```
+
+## Cline (VS Code)
+MCP settings → **Add MCP server** → stdio. Command `google-drive-files-mcp`, args `serve`.
+
+## Continue.dev — `~/.continue/config.yaml`
+```yaml
+mcpServers:
+  - name: google-drive-files
+    command: google-drive-files-mcp
+    args:
+      - serve
+```
+
+## One-time auth per machine
+Once `google-drive-files-mcp setup` has cached a token at `~/.config/google-drive-files-mcp/token.json`, every client on that machine/user reuses it — no per-client re-authentication.

google_drive_files_mcp-0.3.0/docs/setup-google-oauth.md

@@ -0,0 +1,56 @@
+# Google OAuth setup (~10 minutes)
+
+This server **moves and organizes files in your Drive**, so it needs the **full `drive` scope** (read + write + delete on all your Drive files). There is no narrower scope that can change a file's parents. Treat the cached token like a password.
+
+You create your own OAuth client; nothing is shipped with the package, and nothing leaves your machine.
+
+## Step 1 — Project
+1. [Google Cloud Console](https://console.cloud.google.com/) → sign in → project dropdown → **New Project** → name it → **Create** → switch to it.
+
+## Step 2 — Enable the Drive API
+[console.cloud.google.com/apis/library/drive.googleapis.com](https://console.cloud.google.com/apis/library/drive.googleapis.com) → **Enable**.
+
+## Step 3 — OAuth consent screen
+Left nav → **APIs & Services** → **OAuth consent screen**.
+
+| You have | Pick | Why |
+|---|---|---|
+| Google Workspace | **Internal** | No verification needed *even for the restricted full-`drive` scope* |
+| Personal Gmail | **External** | Add your address under **Test users** or consent is refused |
+
+Fill App name / support email / developer contact. Leave the Scopes page empty. Save.
+
+## Step 4 — OAuth client
+**Credentials → + Create Credentials → OAuth client ID → Desktop app → Create → Download JSON.**
+
+## Step 5 — Hand it to the CLI
+```bash
+google-drive-files-mcp setup --import-credentials ~/Downloads/client_secret_*.json
+```
+A browser opens; the consent screen will say **"See, edit, create, and delete all of your Google Drive files"** — that breadth is required to move arbitrary files. The refresh token is cached at `~/.config/google-drive-files-mcp/token.json` (mode `0600`).
+
+Verify:
+```bash
+google-drive-files-mcp status
+google-drive-files-mcp search "Reports" --folders
+```
+
+## Common errors
+
+**`HttpError 403: Google Drive API has not been used in project … or it is disabled`**
+Enable the Drive API (Step 2) on the project that owns your OAuth client, then wait ~1 min and retry.
+
+**`Access blocked: This app's request is invalid`**
+Personal Gmail without your address under **Test users**. Add it on the consent screen.
+
+**`This app isn't verified`**
+Expected for an unverified personal app. **Advanced → Go to <app> (unsafe)**. Verification only matters for public distribution.
+
+**`HttpError 403: insufficientFilePermissions` / `insufficientPermissions` when moving**
+The token was authorized with a narrower scope. Re-authorize with the full scope:
+```bash
+google-drive-files-mcp setup --reauth
+```
+
+**Browser opened but never returned**
+Firewall blocking the localhost redirect. Re-run `setup` (new port each time) or allow the connection.

google_drive_files_mcp-0.3.0/examples/file-into-dated-folder.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Move a file into a YYYY-MM folder (created if missing) under a parent folder.
+# Handy for filing exports/reports into month buckets.
+#
+# Usage:
+#   ./file-into-dated-folder.sh <file-url-or-id> [parent-folder-name-or-id]
+#
+# Assumes google-drive-files-mcp is installed and `setup` has been run once.
+
+set -euo pipefail
+
+FILE="${1:?usage: file-into-dated-folder.sh <file-url-or-id> [parent]}"
+PARENT="${2:-root}"
+MONTH="$(date +%Y-%m)"
+
+# Create (or reuse) the YYYY-MM folder under PARENT, capture its id.
+FOLDER_ID="$(
+  google-drive-files-mcp mkdir "${MONTH}" --parent "${PARENT}" \
+    | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])'
+)"
+
+google-drive-files-mcp move "${FILE}" "${FOLDER_ID}"
+echo "filed ${FILE} into ${MONTH} (folder ${FOLDER_ID})"