# Google Drive API Reference

Complete API documentation for all Google Drive tools in the FastMCP Google MCP Server.

## Available Tools

| Tool Name | Description |
|-----------|-------------|
| [`upload_file_to_drive`](#upload_file_to_drive) | Upload local files to Google Drive |
| [`search_drive_files`](#search_drive_files) | Search for files and folders using query syntax |
| [`get_drive_file_content`](#get_drive_file_content) | Retrieve content of any Drive file |
| [`list_drive_items`](#list_drive_items) | List files and folders in a directory |
| [`create_drive_file`](#create_drive_file) | Create new files directly in Drive |
| [`manage_drive_files`](#manage_drive_files) | Move, copy, rename, or delete files (unified file operations) |
| [`share_drive_files`](#share_drive_files) | Share files with specific users |
| [`make_drive_files_public`](#make_drive_files_public) | Make files publicly accessible |
| [`start_google_auth`](#start_google_auth) | Initiate OAuth authentication |
| [`check_drive_auth`](#check_drive_auth) | Check authentication status |

---

## upload_file_to_drive

Upload a local file to Google Drive with authentication and folder management.

### Parameters

| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `user_google_email` | string | Yes | User's Google email address | - |
| `filepath` | string | Yes | Path to the local file to upload | - |
| `folder_id` | string | No | Google Drive folder ID | `"root"` |
| `filename` | string | No | Custom filename for the uploaded file | Original filename |

### Returns

```json
{
  "file_id": "1234567890abcdef",
  "file_name": "document.pdf",
  "web_view_link": "https://drive.google.com/file/d/1234567890abcdef/view",
  "download_link": "https://drive.google.com/uc?export=download&id=1234567890abcdef",
  "size": "2.5 MB",
  "mime_type": "application/pdf",
  "folder_id": "root",
  "created_time": "2024-01-15T10:30:00Z"
}
```

### Example Usage

```python
result = await upload_file_to_drive(
    user_google_email="user@gmail.com",
    filepath="/home/user/documents/report.pdf",
    folder_id="1ABC2DEF3GHI",
    filename="Q4_Report_2024.pdf"
)
```

### Error Scenarios

- `AUTH_REQUIRED`: User hasn't authenticated or token expired
- `FILE_NOT_FOUND`: Local file doesn't exist
- `FOLDER_NOT_FOUND`: Specified folder_id doesn't exist or not accessible
- `QUOTA_EXCEEDED`: Drive storage quota exceeded
- `FILE_TOO_LARGE`: File exceeds Google Drive size limits

---

## search_drive_files

Search for files and folders in Google Drive using advanced query syntax.

### Parameters

| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `user_google_email` | string | Yes | User's Google email address | - |
| `query` | string | Yes | Google Drive query string (see query syntax below) | - |
| `page_size` | integer | No | Number of results to return (1-100) | 10 |
| `drive_id` | string | No | Specific shared drive ID to search | - |
| `include_items_from_all_drives` | boolean | No | Include shared drive items | true |
| `corpora` | string | No | Corpus to search (`user`, `allDrives`, `domain`) | - |

### Query Syntax Examples

```
# Search by name
name contains 'report'
name = 'Exact Report Name.pdf'

# Search by type
mimeType = 'application/pdf'
mimeType = 'application/vnd.google-apps.folder'

# Search by modification date
modifiedTime > '2024-01-01T00:00:00'
modifiedTime >= '2024-01-01' and modifiedTime <= '2024-12-31'

# Search in specific folder
'folder_id' in parents

# Search for files owned by specific user
'user@example.com' in owners

# Complex queries
name contains 'report' and mimeType = 'application/pdf' and modifiedTime > '2024-01-01'
```

### Returns

```json
{
  "files": [
    {
      "id": "1234567890abcdef",
      "name": "Q4 Report.pdf",
      "mimeType": "application/pdf",
      "size": "2048576",
      "createdTime": "2024-01-10T08:00:00Z",
      "modifiedTime": "2024-01-15T10:30:00Z",
      "webViewLink": "https://drive.google.com/file/d/1234567890abcdef/view",
      "parents": ["folder_id"],
      "owners": [{"emailAddress": "owner@gmail.com", "displayName": "Owner Name"}],
      "shared": false
    }
  ],
  "nextPageToken": "token_for_next_page"
}
```

### Example Usage

```python
# Search for PDF reports modified this year
result = await search_drive_files(
    user_google_email="user@gmail.com",
    query="name contains 'report' and mimeType = 'application/pdf' and modifiedTime > '2024-01-01'",
    page_size=20
)

# Search in a specific folder
result = await search_drive_files(
    user_google_email="user@gmail.com",
    query="'1ABC2DEF3GHI' in parents",
    page_size=50
)
```

---

## get_drive_file_content

Retrieve the content of a Google Drive file, supporting multiple formats including Google Docs, Sheets, Office files, PDFs, and text files.

### Parameters

| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `user_google_email` | string | Yes | User's Google email address | - |
| `file_id` | string | Yes | Google Drive file ID | - |

### Returns

Content format varies by file type:

**Text/Document files:**
```json
{
  "content": "File content as text...",
  "metadata": {
    "name": "document.txt",
    "mimeType": "text/plain",
    "size": "1024",
    "modifiedTime": "2024-01-15T10:30:00Z"
  }
}
```

**Google Docs/Sheets:**
```json
{
  "content": "Exported content as plain text...",
  "format": "text/plain",
  "original_type": "application/vnd.google-apps.document",
  "metadata": {...}
}
```

**Binary files (PDFs, images):**
```json
{
  "content_type": "binary",
  "download_url": "https://drive.google.com/uc?export=download&id=...",
  "web_view_link": "https://drive.google.com/file/d/.../view",
  "metadata": {...}
}
```

### Supported File Types

- **Google Workspace**: Docs, Sheets, Slides, Forms (exported as text/HTML)
- **Microsoft Office**: .docx, .xlsx, .pptx (converted and extracted)
- **Text files**: .txt, .md, .csv, .json, .xml, .yaml
- **PDFs**: Metadata returned with download link
- **Images**: Metadata with view/download links
- **Other**: Binary files return download links

### Example Usage

```python
# Get content of a Google Doc
content = await get_drive_file_content(
    user_google_email="user@gmail.com",
    file_id="1ABC2DEF3GHI4JKL"
)
```

---

## list_drive_items

List files and folders in a Google Drive directory, including shared drives.

### Parameters

| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `user_google_email` | string | Yes | User's Google email address | - |
| `folder_id` | string | No | Folder ID to list contents | `"root"` |
| `page_size` | integer | No | Number of items to return (1-100) | 100 |
| `drive_id` | string | No | Specific shared drive ID | - |
| `include_items_from_all_drives` | boolean | No | Include shared drive items | true |
| `corpora` | string | No | Corpus to search | - |

### Returns

```json
{
  "items": [
    {
      "id": "folder_123",
      "name": "Documents",
      "type": "folder",
      "mimeType": "application/vnd.google-apps.folder",
      "createdTime": "2024-01-01T00:00:00Z",
      "modifiedTime": "2024-01-15T10:30:00Z"
    },
    {
      "id": "file_456",
      "name": "Report.pdf",
      "type": "file",
      "mimeType": "application/pdf",
      "size": "2048576",
      "webViewLink": "https://drive.google.com/file/d/file_456/view"
    }
  ],
  "folder_name": "My Drive",
  "total_items": 25,
  "nextPageToken": "next_page_token"
}
```

### Example Usage

```python
# List root directory
items = await list_drive_items(
    user_google_email="user@gmail.com",
    folder_id="root",
    page_size=50
)

# List specific folder
items = await list_drive_items(
    user_google_email="user@gmail.com",
    folder_id="1ABC2DEF3GHI",
    page_size=100
)
```

---

## create_drive_file

Create a new file in Google Drive from content or URL.

### Parameters

| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `user_google_email` | string | Yes | User's Google email address | - |
| `file_name` | string | Yes | Name for the new file | - |
| `content` | string | No* | Text content for the file | - |
| `folder_id` | string | No | Parent folder ID | `"root"` |
| `mime_type` | string | No | MIME type of the content | `"text/plain"` |
| `fileUrl` | string | No* | URL to download file content from | - |

\* Either `content` or `fileUrl` must be provided

### Returns

```json
{
  "file_id": "1234567890abcdef",
  "name": "new_document.txt",
  "mimeType": "text/plain",
  "webViewLink": "https://drive.google.com/file/d/1234567890abcdef/view",
  "createdTime": "2024-01-15T10:30:00Z",
  "size": "1024"
}
```

### Example Usage

```python
# Create from text content
result = await create_drive_file(
    user_google_email="user@gmail.com",
    file_name="notes.txt",
    content="Meeting notes from today...",
    mime_type="text/plain"
)

# Create from URL
result = await create_drive_file(
    user_google_email="user@gmail.com",
    file_name="downloaded_image.jpg",
    fileUrl="https://example.com/image.jpg",
    mime_type="image/jpeg"
)

# Create Google Doc
result = await create_drive_file(
    user_google_email="user@gmail.com",
    file_name="New Document",
    content="Document content...",
    mime_type="application/vnd.google-apps.document"
)
```

---

## manage_drive_files

Unified tool for Google Drive file management: move, copy, rename, or delete files in a single operation.

### Parameters

| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `user_google_email` | string | Yes | User's Google email address | - |
| `operation` | string | Yes | Operation: `move`, `copy`, `rename`, or `delete` | - |
| `file_ids` | array[string] | Conditional* | List of file IDs to operate on | - |
| `target_folder_id` | string | Conditional** | Target folder ID for move/copy | - |
| `remove_from_all_parents` | boolean | No | Remove file from ALL parent folders (move only) | true |
| `name_prefix` | string | No | Prefix for copied file names (copy only) | `"Copy of "` |
| `new_name` | string | Conditional*** | New filename (rename only) | - |
| `permanent` | boolean | No | Permanently delete vs. move to trash (delete only) | false |

\* Required for all operations
\*\* Required for `move` operation, optional for `copy`
\*\*\* Required for `rename` operation

### Returns

**Move/Copy/Rename Success:**
```json
{
  "operation": "move",
  "success": true,
  "results": [
    {
      "file_id": "1ABC2DEF3GHI",
      "file_name": "document.pdf",
      "status": "success",
      "new_location": "folder_id_123"
    }
  ],
  "summary": {
    "total": 5,
    "successful": 4,
    "failed": 1
  }
}
```

**Delete Success:**
```json
{
  "operation": "delete",
  "success": true,
  "deleted_files": [
    {
      "file_id": "1ABC2DEF3GHI",
      "file_name": "old_document.pdf",
      "permanently_deleted": false
    }
  ],
  "total_deleted": 3
}
```

### Permission Errors

Common permission errors encountered with shared drives:

| Error Code | Description | When It Occurs |
|------------|-------------|----------------|
| `insufficientFilePermissions` | Insufficient permissions to modify file | File owned by another user in shared drive |
| `cannotAddParent` | Cannot add parent folder | File already has multiple parents |
| `teamDrivesParentLimit` | Shared drive parent limit | Shared drive files must have exactly one parent |

**Important:** Most shared drive files cannot be moved by non-owners. These files should remain in their current locations for proper team collaboration.

### Example Usage

```python
# Move files to a new folder (removing from all current locations)
result = await manage_drive_files(
    user_google_email="user@gmail.com",
    operation="move",
    file_ids=["file_id_1", "file_id_2", "file_id_3"],
    target_folder_id="new_folder_id",
    remove_from_all_parents=True
)

# Copy files with custom prefix
result = await manage_drive_files(
    user_google_email="user@gmail.com",
    operation="copy",
    file_ids=["file_id_1"],
    target_folder_id="backup_folder_id",
    name_prefix="Backup - "
)

# Rename a single file
result = await manage_drive_files(
    user_google_email="user@gmail.com",
    operation="rename",
    file_ids=["file_id_1"],
    new_name="Updated Document Name.pdf"
)

# Move to trash (recoverable)
result = await manage_drive_files(
    user_google_email="user@gmail.com",
    operation="delete",
    file_ids=["file_id_1", "file_id_2"],
    permanent=False
)

# Permanently delete files
result = await manage_drive_files(
    user_google_email="user@gmail.com",
    operation="delete",
    file_ids=["file_id_1"],
    permanent=True
)
```

### Real-World Insights

From production use organizing 100+ files:
- ✅ **90% of files** in shared drives have permission restrictions
- ✅ **Only owner-created files** can typically be moved/renamed
- ✅ **Shared drive files** should stay in their current locations for collaboration
- ✅ **Use `remove_from_all_parents=True`** for clean folder reorganization
- ⚠️ **Always handle permission errors gracefully** - they're expected for team files

---

## share_drive_files

Share Google Drive files with specific people via email addresses.

### Parameters

| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `user_google_email` | string | Yes | User's Google email address | - |
| `file_ids` | array[string] | Yes | List of file IDs to share | - |
| `email_addresses` | array[string] | Yes | Email addresses to share with | - |
| `role` | string | No | Permission role (`reader`, `writer`, `commenter`) | `"reader"` |
| `send_notification` | boolean | No | Send email notification | true |
| `message` | string | No | Custom message for notification | - |

### Returns

```json
{
  "shared_files": [
    {
      "file_id": "1234567890abcdef",
      "file_name": "document.pdf",
      "shared_with": ["user1@gmail.com", "user2@gmail.com"],
      "role": "reader",
      "notification_sent": true
    }
  ],
  "errors": []
}
```

### Example Usage

```python
result = await share_drive_files(
    user_google_email="owner@gmail.com",
    file_ids=["file_id_1", "file_id_2"],
    email_addresses=["colleague@gmail.com", "partner@company.com"],
    role="writer",
    send_notification=true,
    message="Please review these documents"
)
```

---

## make_drive_files_public

Make Google Drive files publicly accessible (anyone with the link can view).

### Parameters

| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `user_google_email` | string | Yes | User's Google email address | - |
| `file_ids` | array[string] | Yes | List of file IDs to make public | - |
| `public` | boolean | No | True to make public, false to revoke | true |
| `role` | string | No | Permission role (`reader`, `writer`) | `"reader"` |

### Returns

```json
{
  "updated_files": [
    {
      "file_id": "1234567890abcdef",
      "file_name": "public_document.pdf",
      "is_public": true,
      "public_link": "https://drive.google.com/file/d/1234567890abcdef/view?usp=sharing",
      "role": "reader"
    }
  ],
  "errors": []
}
```

### Example Usage

```python
# Make files public
result = await make_drive_files_public(
    user_google_email="user@gmail.com",
    file_ids=["file_id_1", "file_id_2"],
    public=true,
    role="reader"
)

# Revoke public access
result = await make_drive_files_public(
    user_google_email="user@gmail.com",
    file_ids=["file_id_1"],
    public=false
)
```

---

## start_google_auth

Initiate Google OAuth2 authentication flow for Google services.

### Parameters

| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `user_google_email` | string | Yes | User's Google email address | - |
| `service_name` | string | No | Display name for the service | `"Google Services"` |

### Returns

```json
{
  "auth_url": "https://accounts.google.com/o/oauth2/v2/auth?...",
  "message": "Please visit the URL to complete authentication",
  "session_id": "session_123",
  "expires_in": 600
}
```

### Example Usage

```python
auth_info = await start_google_auth(
    user_google_email="user@gmail.com",
    service_name="Google Drive"
)
# User visits auth_url to complete OAuth flow
```

---

## check_drive_auth

Verify Google Drive authentication status for a specific user account.

### Parameters

| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `user_google_email` | string | Yes | User's Google email address | - |

### Returns

```json
{
  "authenticated": true,
  "user_email": "user@gmail.com",
  "scopes": [
    "https://www.googleapis.com/auth/drive",
    "https://www.googleapis.com/auth/drive.file"
  ],
  "token_expiry": "2024-01-15T12:30:00Z",
  "quota_info": {
    "storage_used": "5.2 GB",
    "storage_limit": "15 GB",
    "storage_percentage": 34.67
  }
}
```

### Example Usage

```python
status = await check_drive_auth(
    user_google_email="user@gmail.com"
)

if not status["authenticated"]:
    # Need to run start_google_auth
    pass
```

---

## Common Error Codes

| Error Code | Description | Resolution |
|------------|-------------|------------|
| `AUTH_REQUIRED` | User needs to authenticate | Run `start_google_auth` |
| `TOKEN_EXPIRED` | OAuth token has expired | Automatic refresh attempted, may need re-auth |
| `PERMISSION_DENIED` | Insufficient permissions for operation | Check file ownership/sharing settings |
| `insufficientFilePermissions` | Cannot modify file (shared drive) | File owned by another user - leave in current location |
| `cannotAddParent` | Cannot add parent folder | File has multiple parents or is in shared drive |
| `teamDrivesParentLimit` | Shared drive parent limit exceeded | Shared drive files must have exactly one parent |
| `NOT_FOUND` | File or folder not found | Verify ID exists and is accessible |
| `QUOTA_EXCEEDED` | API quota or storage limit exceeded | Wait for quota reset or upgrade storage |
| `INVALID_PARAMETER` | Invalid parameter value | Check parameter format and requirements |
| `RATE_LIMITED` | Too many requests | Wait before retrying |

## Best Practices

### Authentication & Authorization
1. **Authentication**: Always check auth status before operations using `check_drive_auth`
2. **Permissions**: Be aware that 90%+ of shared drive files have permission restrictions
3. **Ownership**: Only file owners can typically move, rename, or delete files in shared drives

### File Operations
4. **Batch Operations**: Use `share_drive_files` and `manage_drive_files` for multiple files instead of individual calls
5. **Move vs Copy**: Use `remove_from_all_parents=True` when moving files to avoid duplicate parent relationships
6. **Permission Errors**: Always handle `insufficientFilePermissions`, `cannotAddParent`, and `teamDrivesParentLimit` errors gracefully
7. **Shared Drive Files**: Keep team collaboration files in their current shared drive locations - moving them can break workflows

### Search & Organization
8. **Query Optimization**: Use specific queries to reduce API calls and improve search accuracy
9. **Free-text Search**: For year-based searches (e.g., "2025"), free-text queries often work better than structured date queries
10. **File Verification**: Use `get_drive_file_content` to verify file categorization before bulk operations
11. **Test First**: Always test file operations with a small subset before bulk processing

### API Efficiency
12. **Error Handling**: Implement retry logic for transient errors with exponential backoff
13. **Pagination**: Handle `nextPageToken` for large result sets (100+ files)
14. **MIME Types**: Use Google MIME types for native Google Workspace files
15. **Rate Limiting**: Tools handle rate limiting automatically, but be mindful of quota limits

### Real-World Lessons
16. **Organization Strategy**: Focus on personally-owned files; shared drive files are already organized by teams
17. **Documentation**: Create summary documents to track file organization and decisions
18. **Incremental Approach**: Process files in batches and verify results before proceeding
19. **Permission Awareness**: ~90% of modern workplace files are in shared drives with restricted permissions

## Rate Limits

Google Drive API has the following limits:
- **Queries per day**: 1,000,000,000
- **Queries per 100 seconds per user**: 1,000
- **Queries per 100 seconds**: 10,000

Tools automatically handle rate limiting with exponential backoff.

---

For more information, see the [main API documentation](../README.md) or [Google Drive API documentation](https://developers.google.com/drive/api/v3/reference).