# Google Drive MCP Server

Connect Google Drive to Claude Code with a simple double-click setup. This MCP server allows Claude to read, create, update, and manage files in your Google Drive.

## Prerequisites

- Python 3.10 or higher
- A Google Account (personal or Google Workspace)
- Google Cloud Console access

## Step 1: Create Google Cloud Credentials

### 1.1 Create a Google Cloud Project

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Click the project dropdown at the top of the page
3. Click **New Project**
4. Enter a project name (e.g., "Google Drive MCP")
5. Click **Create**
6. Wait for the project to be created, then select it

### 1.2 Enable the Google Drive API

1. In the Google Cloud Console, go to **APIs & Services** > **Library**
2. Search for "Google Drive API"
3. Click on **Google Drive API**
4. Click **Enable**

### 1.3 Configure OAuth Consent Screen

1. Go to **APIs & Services** > **OAuth consent screen**
2. Select **External** (or **Internal** if using Google Workspace)
3. Click **Create**
4. Fill in the required fields:
   - **App name**: Google Drive MCP
   - **User support email**: Your email
   - **Developer contact email**: Your email
5. Click **Save and Continue**
6. On the **Scopes** page, click **Add or Remove Scopes**
7. Add these scopes:
   - `https://www.googleapis.com/auth/drive.readonly`
   - `https://www.googleapis.com/auth/drive.file`
   - `https://www.googleapis.com/auth/drive`
8. Click **Update**, then **Save and Continue**
9. On the **Test users** page, click **Add Users**
10. Add your email address
11. Click **Save and Continue**

### 1.4 Create OAuth Client ID

1. Go to **APIs & Services** > **Credentials**
2. Click **Create Credentials** > **OAuth client ID**
3. Select **Desktop app** as the application type
4. Enter a name (e.g., "Google Drive MCP Desktop")
5. Click **Create**
6. Click **Download JSON** on the popup
7. Rename the downloaded file to `credentials.json`
8. Place `credentials.json` in the project root directory

**Important:** The credentials must be of type "Desktop app", not "Web application".

## Step 2: Install Dependencies

### Option A: Using Virtual Environment (Recommended)

```bash
# Clone the repository
git clone https://github.com/david-valdivia/GoogleDriveMCP.git
cd GoogleDriveMCP

# Create virtual environment (Python 3.10+ required)
python3 -m venv .venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

### Option B: Global Installation

```bash
pip install -r requirements.txt
```

## Step 3: Run the Setup GUI

```bash
# With virtual environment activated
python -m src.main
```

This opens the setup window where you can:
1. Select your permission level (Read Only, Read + Create, or Full Access)
2. Click "Connect to Google" to authenticate
3. Complete the OAuth flow in your browser
4. Click "Configure MCP" to select a project directory for Claude Code

## Step 4: Build the Executable (Optional)

Build a standalone executable that doesn't require Python:

```bash
# With virtual environment activated
python build/build.py
```

### Build Output

| Platform | Output |
|----------|--------|
| macOS | `build/dist/Google Drive MCP.app` and `build/dist/googledrive-mcp` |
| Windows | `build/dist/googledrive-mcp.exe` |
| Linux | `build/dist/googledrive-mcp` |

### macOS Additional Requirements

If building on macOS, you need Tcl/Tk for the GUI:

```bash
# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python with Tcl/Tk support
brew install python-tk@3.12
```

## Step 5: Configure Claude Code

After authentication, the app automatically creates a `.mcp.json` file in your selected project directory. Alternatively, create it manually:

```json
{
  "mcpServers": {
    "googledrive": {
      "command": "/path/to/googledrive-mcp",
      "args": ["--serve"]
    }
  }
}
```

Replace `/path/to/googledrive-mcp` with:
- **Built executable**: Full path to `googledrive-mcp` or `googledrive-mcp.exe`
- **From source**: Full path to Python and script, e.g.:
  ```json
  {
    "mcpServers": {
      "googledrive": {
        "command": "/path/to/.venv/bin/python",
        "args": ["/path/to/GoogleDriveMCP/src/main.py", "--serve"]
      }
    }
  }
  ```

## Permission Levels

| Level | Scopes | Capabilities |
|-------|--------|--------------|
| **Read Only** | `drive.readonly` | View and search files |
| **Read + Create** | `drive.file` | Above + create new files |
| **Full Access** | `drive` | Read, create, update, delete, share |

## Available MCP Tools

| Tool | Description | Required Permission |
|------|-------------|---------------------|
| `list_files` | List files in a folder or root | Read Only |
| `read_file` | Read file contents (exports Google Docs to text) | Read Only |
| `search_files` | Full-text search across Drive | Read Only |
| `list_folders` | List all folders for navigation | Read Only |
| `get_sharing_info` | View who has access to a file | Read Only |
| `create_file` | Create a new file or Google Doc | Read + Create |
| `create_folder` | Create a new folder | Read + Create |
| `update_file` | Update file contents | Full Access |
| `delete_file` | Move file to trash | Full Access |
| `move_file` | Move file to different folder | Full Access |
| `copy_file` | Copy a file | Full Access |
| `share_file` | Share file with email address | Full Access |

## Development

### Run Tests

```bash
# With virtual environment activated
pytest -v
```

### Project Structure

```
GoogleDriveMCP/
├── src/
│   ├── main.py          # Entry point, mode detection
│   ├── gui.py           # Setup GUI with tkinter
│   ├── server.py        # MCP server implementation
│   ├── drive.py         # Google Drive API wrapper
│   ├── auth.py          # OAuth flow and token management
│   └── config.py        # Platform-specific config paths
├── tests/               # Test files
├── build/
│   ├── build.py         # Build script
│   └── googledrive-mcp.spec  # PyInstaller spec
├── credentials.json     # Your OAuth credentials (not committed)
├── requirements.txt     # Python dependencies
└── README.md
```

### Token Storage Location

Tokens are stored in platform-specific locations:

| Platform | Location |
|----------|----------|
| macOS | `~/Library/Application Support/GoogleDriveMCP/` |
| Windows | `%APPDATA%\GoogleDriveMCP\` |
| Linux | `~/.config/GoogleDriveMCP/` |

## Troubleshooting

### "credentials.json not found"

Make sure `credentials.json` is in the project root directory (same folder as `src/`).

### "Error 400: redirect_uri_mismatch"

Your OAuth credentials are configured as "Web application" instead of "Desktop app". Create new credentials with type "Desktop app".

### "Access blocked: This app's request is invalid"

1. Make sure you added yourself as a test user in the OAuth consent screen
2. Verify the app is in "Testing" mode (not "In production")

### "ModuleNotFoundError: No module named 'tkinter'"

On macOS with Homebrew Python:
```bash
brew install python-tk@3.12
```

On Ubuntu/Debian:
```bash
sudo apt-get install python3-tk
```

### MCP server not connecting in Claude Code

1. Verify the path in `.mcp.json` is correct and absolute
2. Restart Claude Code after creating/modifying `.mcp.json`
3. Check that the executable has execute permissions: `chmod +x googledrive-mcp`

## License

MIT