# google-drive-mcp

MCP server to browse and manage Google Drive: search files, read Docs/Sheets
content, move/rename/copy files and folders, manage the trash, permissions,
revision history and comments.

## Tools (27)

### Browsing and reading

| Tool | What it does |
|---|---|
| `list_folder` | List the contents of a folder (root by default) |
| `search_files` | Search files by name, content, type, folder or modified date |
| `get_file_metadata` | Metadata of a file (name, type, size, owner, URL) |
| `read_doc_content` | Read a Google Doc's content as text |
| `read_sheet_as_csv` | Read a Google Sheet as CSV |
| `download_file` | Download the real binary content of a file already stored in Drive (PDFs, images, ZIPs) — capped at 10 MB. Different from `read_doc_content`/`read_sheet_as_csv`, which export a native Google Doc/Sheet; use those instead of `download_file` for native Docs/Sheets |
| `get_folder_path` | Full folder breadcrumb path to a file |

### Organizing

| Tool | What it does |
|---|---|
| `move_file` | Move a file to another folder |
| `rename_file` | Rename a file or folder |
| `copy_file` | Duplicate a file, e.g. to start from a template without touching the original |
| `create_folder` | Create a new folder |

### Trash

| Tool | What it does |
|---|---|
| `trash_file` | Send a file to the trash — reversible with `restore_file` (Google keeps trashed files for 30 days) |
| `restore_file` | Take a file out of the trash |

### Permissions

| Tool | What it does |
|---|---|
| `list_permissions` | List who has access to a file and with what role |
| `share_file` | Share a file with a person, a domain, or anyone with the link |
| `remove_permission` | Revoke someone's access to a file |

### Revision history

| Tool | What it does |
|---|---|
| `list_revisions` | List a file's saved past versions (Docs, Sheets, Slides) |
| `get_revision_content` | Read the content of a specific old revision of a Doc/Sheet without restoring it — useful for recovering text from an overwritten report |

### Comments

| Tool | What it does |
|---|---|
| `list_comments` | List a file's comments (Docs, Sheets, Slides) |
| `add_comment` | Add a general comment to a file (not anchored to a specific point) |
| `reply_to_comment` | Reply to an existing comment |
| `resolve_comment` | Mark a comment as resolved (adds a reply with a "resolve" action, same as the ✓ button in the UI) |
| `delete_comment` | Delete a comment and its replies |

### Shared drives, storage and change tracking

| Tool | What it does |
|---|---|
| `list_shared_drives` | List the shared drives visible to this account |
| `about_storage` | Storage quota: used, limit, and how much each type takes up |
| `get_changes_start_token` | Get the token that marks "now", to start watching for changes |
| `list_changes` | List what has changed in Drive since a given token — watch a client folder without re-reading it from scratch each time |

## Safety

- Every tool carries MCP Tool Annotations from the spec (`readOnlyHint`, `destructiveHint`,
  `idempotentHint`, `openWorldHint`).
- Execution errors propagate as real MCP protocol errors (`isError=true`) — never as a JSON
  payload that looks like a success.
- Sensitive operations carry a `confirmed: bool = False` parameter. Without it, the tool returns a
  preview of what it would do instead of executing: `trash_file`, `share_file`,
  `remove_permission`, `delete_comment`. `share_file` is the most sensitive of the set — it exposes
  a document to someone new, so treat the preview as a real gate, not a formality.

## Setup

1. Create a Google Cloud project (or reuse one) and enable the
   **Google Drive API**.
2. Create an OAuth 2.0 Client ID of type "Desktop app" and download it as
   `client_secret.json`.
3. If the app is in "Testing" mode, add your Google account(s) as test users.
4. Install dependencies:
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   ```
5. Run the OAuth flow once per account you want to expose:
   ```bash
   CLIENT_SECRET_PATH=~/.config/google-drive-mcp/client_secret.json \
   TOKEN_OUT=~/.config/google-drive-mcp/token.json \
     python3 setup_auth.py
   ```
   This opens a browser — log in and grant access. Repeat with a different
   `TOKEN_OUT` for each additional account.

## MCP client configuration

```json
{
  "mcpServers": {
    "google-drive": {
      "command": "/path/to/.venv/bin/python3",
      "args": ["/path/to/google-drive-mcp/server.py"],
      "env": {
        "GOOGLE_DRIVE_TOKEN_PATH": "~/.config/google-drive-mcp/token.json"
      }
    }
  }
}
```

| Env var | Default | Purpose |
|---|---|---|
| `GOOGLE_DRIVE_TOKEN_PATH` | `~/.config/google-drive-mcp/token.json` | Path to the OAuth token for this account |

## Notes

- Scope used is `https://www.googleapis.com/auth/drive` (read + write) —
  needed for `move_file`, `rename_file`, `create_folder` and every write tool
  below to work. A `drive.readonly` token will fail on those.
- `search_files` matches on file name by default; pass `search_content=True` to search inside the
  document body instead (Drive's `fullText` search) when you remember what a file says but not
  its name.
- `download_file` is capped at 10 MB to avoid pulling huge binaries into the model's context —
  use it to confirm a file's existence/size beyond that limit, not to read its content.
- If you run this server under two different Google accounts (e.g. one per client workspace), a
  search or read against the wrong account's token does **not** error — it silently returns an
  empty result. Don't conclude a file doesn't exist without checking you're on the right account.

## License

MIT — see [LICENSE](LICENSE).