Metadata-Version: 2.4
Name: workos-gdrive-mcp-server
Version: 1.0.0
Summary: MCP server for Google Drive — list, search, read, upload, share, and manage files via Google OAuth2.
Author: WorkOS Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/workos/workos-gdrive-mcp-server
Project-URL: Repository, https://github.com/workos/workos-gdrive-mcp-server
Project-URL: Issues, https://github.com/workos/workos-gdrive-mcp-server/issues
Keywords: mcp,google-drive,model-context-protocol,ai-tools,cloud-storage
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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 :: Software Development :: Libraries
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: google-auth>=2.0.0
Requires-Dist: google-api-python-client>=2.0.0

# Google Drive MCP Server

An independent MCP (Model Context Protocol) server for Google Drive operations. List, search, read, upload, share, and manage files and folders in Google Drive via OAuth2.

## Features

- 📁 **List Files** — Browse files in any folder with sorting and pagination
- 🔍 **Search Files** — Full-text search or advanced Drive query syntax
- 📄 **Read Files** — Read Google Docs, Sheets, Slides as text/CSV, or any text file
- ⬆️ **Upload Files** — Upload files to any folder
- 📂 **Create Folders** — Organize files with new folders
- 🔗 **Share Files** — Share with users as reader, commenter, or writer
- 📦 **Move Files** — Move between folders
- 🗑️ **Delete Files** — Move files to trash (recoverable)

## Installation

```bash
pip install workos-gdrive-mcp-server
```

## Prerequisites

You need Google OAuth2 credentials with the **Google Drive API** scope enabled.

### Getting Credentials

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create/select a project → Enable the **Google Drive API**
3. Create OAuth 2.0 credentials (Desktop app type)
4. Generate a refresh token using the helper script or OAuth Playground

The refresh token must include the scope:
```
https://www.googleapis.com/auth/drive
```

> **Tip**: If you already have tokens for Gmail/GMeet with the same Google project,
> you can generate a new refresh token that includes Drive scope along with your existing scopes.

## Quick Start

```bash
GOOGLE_CLIENT_ID=your-client-id \
GOOGLE_CLIENT_SECRET=your-client-secret \
GOOGLE_REFRESH_TOKEN=your-refresh-token \
gdrive-mcp-server
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `GOOGLE_CLIENT_ID` | ✅ | Google OAuth2 client ID |
| `GOOGLE_CLIENT_SECRET` | ✅ | Google OAuth2 client secret |
| `GOOGLE_REFRESH_TOKEN` | ✅ | OAuth2 refresh token with Drive scope |
| `GDRIVE_LOG_LEVEL` | ❌ | Log level (default: INFO) |

## Available Tools

### Read Operations

#### `gdrive_list_files`
List files in Google Drive, optionally within a specific folder.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `folder_id` | string | `""` | Folder ID (empty = all files) |
| `max_results` | int | `20` | Results per page (1-100) |
| `page_token` | string | `""` | Pagination token |
| `order_by` | string | `"modifiedTime desc"` | Sort order |

#### `gdrive_search_files`
Search for files by name, content, or advanced query.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | string | — | Search keywords or Drive query syntax |
| `max_results` | int | `20` | Results per page (1-100) |
| `page_token` | string | `""` | Pagination token |

#### `gdrive_get_file_info`
Get detailed metadata for a specific file.

| Parameter | Type | Description |
|-----------|------|-------------|
| `file_id` | string | Google Drive file ID |

#### `gdrive_read_file`
Read the text content of a file. Google Workspace files are auto-exported.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_id` | string | — | Google Drive file ID |
| `max_chars` | int | `50000` | Max characters to return |

### Write Operations

#### `gdrive_create_folder`
Create a new folder.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | string | — | Folder name |
| `parent_id` | string | `""` | Parent folder (empty = root) |

#### `gdrive_upload_file`
Upload a file (content as base64).

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | string | — | File name |
| `content_base64` | string | — | Base64-encoded content |
| `mime_type` | string | `"application/octet-stream"` | MIME type |
| `parent_id` | string | `""` | Parent folder (empty = root) |

#### `gdrive_share_file`
Share a file with a user.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_id` | string | — | File to share |
| `email` | string | — | User email |
| `role` | string | `"reader"` | `reader`, `commenter`, or `writer` |
| `notify` | bool | `true` | Send notification email |

#### `gdrive_move_file`
Move a file to a different folder.

| Parameter | Type | Description |
|-----------|------|-------------|
| `file_id` | string | File to move |
| `new_parent_id` | string | Destination folder ID |

#### `gdrive_delete_file`
Move a file to trash (recoverable).

| Parameter | Type | Description |
|-----------|------|-------------|
| `file_id` | string | File to trash |

## Adding to AI Applications

### Claude Desktop / Cursor / Windsurf

```json
{
  "mcpServers": {
    "gdrive": {
      "command": "gdrive-mcp-server",
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}
```

### WorkOS

Add via Settings → MCP Servers → Add Server:
- **Name**: `gdrive`
- **Command**: `gdrive-mcp-server`
- **Environment Variables**: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN

## License

MIT
