# Google Drive MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for Google Drive API v3, enabling AI agents like Claude to manage Google Drive files, folders, and sharing.

Provides **26 tools** across 9 categories for comprehensive Google Drive management.

## Features

| Category | Tools | Description |
|----------|-------|-------------|
| **Files** | 10 | List, search, full-text search, read, upload, update, append, export files |
| **Trash** | 3 | Trash, restore, list trash |
| **Folders** | 1 | Create folders |
| **Organization** | 2 | Move, copy files |
| **Sharing** | 5 | Share files, manage permissions, create share links |
| **Metadata** | 2 | Get/update file info |
| **Revisions** | 2 | List revision history, download specific versions |
| **Shared Drives** | 2 | List shared drives, get shared drive info |
| **Utilities** | 1 | Recently accessed files |

## Requirements

- Python >= 3.10
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
- Google Cloud project with Drive API enabled
- OAuth 2.0 credentials (from Google Cloud Console)

## Setup

### 1. Google Cloud Project

1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create a new project
2. Enable **Google Drive API** at **APIs & Services > Library**
3. Create credentials at **APIs & Services > Credentials**:
   - **OAuth 2.0 Client ID** (Desktop app)
4. Download the credentials JSON file

### 2. Installation

```bash
git clone https://github.com/software-engineer-mj/google-drive-mcp.git
cd google-drive-mcp
uv sync
```

### 3. Configuration

```bash
cp .env.example .env
```

| Variable | Required | Description |
|----------|----------|-------------|
| `GOOGLE_DRIVE_CREDENTIALS_PATH` | Yes | Path to OAuth 2.0 credentials JSON |
| `GOOGLE_DRIVE_TOKEN_PATH` | No | OAuth token storage path (default: `token.json`) |
| `GOOGLE_DRIVE_MAX_DOWNLOAD_MB` | No | Maximum download size in MB (default: 10) |

### Authentication

On first run, a browser will open for Google account authorization. After approval, `token.json` is created and refreshed automatically.

> **Note:** Never commit `credentials.json` or `token.json` to version control. They are already in `.gitignore`.

## Usage

### stdio (default)

```bash
uv run python -m google_drive_mcp
```

### Docker

```bash
docker build -t google-drive-mcp .

docker run -v /path/to/credentials.json:/app/credentials.json \
           -e GOOGLE_DRIVE_CREDENTIALS_PATH=/app/credentials.json \
           google-drive-mcp
```

## MCP Client Configuration

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "google-drive": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/google-drive-mcp", "python", "-m", "google_drive_mcp"],
      "env": {
        "GOOGLE_DRIVE_CREDENTIALS_PATH": "/path/to/credentials.json",
        "GOOGLE_DRIVE_TOKEN_PATH": "/path/to/token.json"
      }
    }
  }
}
```

### Claude Code

Add to `.mcp.json`:

```json
{
  "mcpServers": {
    "google-drive": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/google-drive-mcp", "python", "-m", "google_drive_mcp"],
      "env": {
        "GOOGLE_DRIVE_CREDENTIALS_PATH": "/path/to/credentials.json",
        "GOOGLE_DRIVE_TOKEN_PATH": "/path/to/token.json"
      }
    }
  }
}
```

## Development

```bash
# Install with dev dependencies
uv sync --dev

# Run tests
uv run pytest tests/ -v

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/
```

## Tool Reference

### Files (10)

| Tool | Description |
|------|-------------|
| `list_files` | List files in Drive, optionally within a folder |
| `search_files` | Search files using Drive query syntax |
| `search_file_content` | Search files by their text content (full-text search) |
| `read_file` | Read file content (Google Docs/Sheets/Slides auto-exported to text/CSV) |
| `upload_file` | Upload a text file |
| `upload_binary_file` | Upload a binary file (base64-encoded) |
| `update_file_content` | Update existing file content |
| `append_to_file` | Append text to the end of an existing text file |
| `export_file` | Export Google Workspace file to PDF, DOCX, XLSX, etc. |
| `create_google_doc` | Create a new Google Docs, Sheets, or Slides |

### Trash (3)

| Tool | Description |
|------|-------------|
| `trash_file` | Move file to trash (recoverable) |
| `restore_file` | Restore file from trash |
| `list_trash` | List files in trash |

### Folders (1)

| Tool | Description |
|------|-------------|
| `create_folder` | Create a new folder |

### Organization (2)

| Tool | Description |
|------|-------------|
| `move_file` | Move file to a different folder |
| `copy_file` | Copy a file |

### Sharing (5)

| Tool | Description |
|------|-------------|
| `share_file` | Share file by email (reader/writer/commenter/owner) |
| `list_permissions` | List file permissions |
| `remove_permission` | Remove a permission |
| `create_share_link` | Create "anyone with link" share link |
| `update_permission` | Update existing permission role |

### Metadata (2)

| Tool | Description |
|------|-------------|
| `get_file_info` | Get detailed file metadata |
| `update_metadata` | Update file name/description |

### Revisions (2)

| Tool | Description |
|------|-------------|
| `list_revisions` | List file revision history |
| `get_revision` | Download specific revision content |

### Shared Drives (2)

| Tool | Description |
|------|-------------|
| `list_shared_drives` | List all shared drives the user has access to |
| `get_shared_drive` | Get metadata for a specific shared drive |

### Utilities (1)

| Tool | Description |
|------|-------------|
| `list_recent` | List recently accessed files |

## Google Docs Auto-Conversion

`read_file` automatically converts Google Workspace files:

| Source Format | Export Format |
|---------------|-------------|
| Google Docs | Plain Text |
| Google Sheets | CSV |
| Google Slides | Plain Text |

`export_file` supports additional formats:

| Source Format | Supported Formats |
|---------------|-------------------|
| Google Docs | pdf, docx, odt, txt, html |
| Google Sheets | pdf, xlsx, ods, csv, tsv |
| Google Slides | pdf, pptx, txt |
| Google Drawings | pdf, png, svg |

## Project Structure

```
src/google_drive_mcp/
├── __init__.py          # FastMCP server instance
├── __main__.py          # Entry point with auto-discovery
├── auth.py              # OAuth 2.0 authentication
├── client.py            # Google Drive API wrapper
├── exceptions.py        # Custom exception hierarchy
├── lifespan.py          # Server lifecycle management
├── utils.py             # MIME type mapping, helpers
├── validators.py        # Input validation utilities
└── tools/
    ├── __init__.py
    ├── drives.py        # Shared drives management
    ├── files.py         # File CRUD operations
    ├── folders.py       # Folder management
    ├── metadata.py      # File metadata
    ├── organization.py  # Move, copy
    ├── revisions.py     # Revision history
    ├── sharing.py       # Sharing and permissions
    ├── trash.py         # Trash operations
    └── utilities.py     # Recently accessed files
tests/
├── conftest.py
├── test_auth.py
├── test_client.py
├── test_server.py
├── test_utils.py
└── tools/
    ├── conftest.py
    └── test_<domain>.py # Tests matching each tool module
```

## License

MIT - see [LICENSE](LICENSE) for details.