Search for files containing "budget" and organize them by moving each one
to the appropriate folder in your Drive hierarchy.

3. Spreadsheet Creation

Create a Google Sheet called "Sales Analysis 2024" with columns for Date, Product,
Quantity, and Revenue to track your sales data.

4. Presentation Creation

Create a presentation called "Product Roadmap" with slides outlining
our Q1 milestones, key features, and timeline.

5. Spreadsheet Updates

Update the "Team Contacts" spreadsheet with new employee information
by modifying specific cells or ranges with the provided data.

6. Document Search

Search for documents in the /Reports folder and create a summary
document listing the files you found.

7. Folder and Document Creation

Create a Templates folder and add standard documents like
a Meeting Notes template, Project Proposal template,
and Budget Spreadsheet template.

Requirements

• Node.js: Version 18 or higher (LTS recommended)
• Google Cloud Project: With the following APIs enabled:
  • Google Drive API
  • Google Docs API
  • Google Sheets API
  • Google Slides API
  • Google Calendar API
• OAuth 2.0 Credentials: Desktop application type (Client ID only - no client secret required)

Google Cloud Setup

1. Create a Google Cloud Project

• Go to the Google Cloud Console
• Click "Select a project" > "New Project"
• Name your project (e.g., "Google Drive MCP")
• Note the Project ID for later

2. Enable Required APIs

• In your project, go to "APIs & Services" > "Library"
• Search for and enable each of these APIs:
  • Google Drive API
  • Google Docs API
  • Google Sheets API
  • Google Slides API
  • Google Calendar API
• Wait for each API to be enabled before proceeding

3. Configure OAuth Consent Screen

• Go to "APIs & Services" > "OAuth consent screen"
• Under 'Branding' fill in the required fields:
  • App name: "My Personal Google Drive MCP"
  • User support email: Your email
  • Developer contact: Your email
• Under 'Audience':
  • Choose "External" (default choice) or "Internal" for Google Workspace accounts
  • Add your email as a test user
• Under 'Data Access' add scopes. The recommended set of scopes for best user experience is the following:
  • ./auth/drive.file
  • .../auth/documents
  • .../auth/spreadsheets
  • .../auth/presentations
  • .../auth/drive
  • .../auth/drive.readonly
  • .../auth/calendar
  • .../auth/calendar.events

4. Create OAuth 2.0 Credentials

• Go to "APIs & Services" > "Credentials"
• Click "+ CREATE CREDENTIALS" > "OAuth client ID"
• Application type: Desktop app (Important!)
• Name: "Google Drive MCP Client"
• Click "Create"
• Download the JSON file
• Rename it to gcp-oauth.keys.json

Installation

Option 1: Use with npx (Recommended)

You can run the server directly without installation:

# Run the server (authentication happens automatically on first run)
npx @piotr-agier/google-drive-mcp

# Optional: Run authentication manually if needed
npx @piotr-agier/google-drive-mcp auth

Option 2: Local Installation

1. Clone and install:

   git clone https://github.com/piotr-agier/google-drive-mcp.git
   cd google-drive-mcp
   npm install
   

2. Set up credentials:

   # Copy the example file
   cp gcp-oauth.keys.example.json gcp-oauth.keys.json
   
   # Edit gcp-oauth.keys.json with your OAuth client ID
   

3. Authenticate (optional):

   npm run auth
   

   Note: Authentication happens automatically on first run of an MCP client if you skip this step.

Docker Usage

Prerequisites

1. Authenticate locally first - Docker containers cannot open browsers for OAuth:

   # Using npx
   npx @piotr-agier/google-drive-mcp auth
   
   # Or using local installation
   npm run auth
   

2. Verify token location:

   ls -la ~/.config/google-drive-mcp/tokens.json
   

Building the Docker Image

1. Build the project (required before Docker build):

   npm install
   npm run build
   

2. Build the Docker image:

   docker build -t google-drive-mcp .
   

Running the Docker Container

The scripts/docker-mcp.sh wrapper manages the container lifecycle — it creates, reuses, and replaces containers automatically. MCP clients invoke this script directly (see configuration below).

To verify the image works after a rebuild:

docker run --rm google-drive-mcp --help

Docker Configuration for Claude Desktop

Option A: Reusable container (recommended)

Uses a wrapper script that keeps a single named container running and reuses it across client restarts — faster startup and no container churn:

{
  "mcpServers": {
    "google-drive": {
      "command": "/path/to/google-drive-mcp/scripts/docker-mcp.sh",
      "env": {
        "GOOGLE_DRIVE_OAUTH_CREDENTIALS": "$HOME/gcp-oauth.keys.json",
        "GOOGLE_DRIVE_MCP_TOKEN_PATH": "$HOME/.config/google-drive-mcp/tokens.json"
      }
    }
  }
}

The script will:

• Create the container on first run
• Reuse the existing container on subsequent runs
• Automatically restart it if it was stopped
• Replace the container when the image has been rebuilt

Note: The container stays running in the background until explicitly stopped. To stop it: docker stop google-drive-mcp

Option B: Fresh container each time

Creates and removes a new container on every client restart:

{
  "mcpServers": {
    "google-drive": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/gcp-oauth.keys.json:/config/gcp-oauth.keys.json:ro",
        "-v",
        "/Users/yourname/.config/google-drive-mcp/tokens.json:/config/tokens.json",
        "google-drive-mcp"
      ]
    }
  }
}

Docker-specific notes:

• Uses -i for interactive mode (required for MCP stdio communication)
• Uses --rm to automatically remove the container after exit
• No port mapping needed (MCP uses stdio, not HTTP)
• Environment variables are set in the Dockerfile

Configuration

OAuth Credentials Configuration

The server supports multiple methods for providing OAuth credentials (in order of priority):

1. Environment Variable (Highest Priority)

export GOOGLE_DRIVE_OAUTH_CREDENTIALS="/path/to/your/gcp-oauth.keys.json"

2. Config Directory (Recommended)

Place gcp-oauth.keys.json in the XDG config directory:

~/.config/google-drive-mcp/gcp-oauth.keys.json

This is the recommended location — it works reliably with npx, global installs, and local setups.

3. Project Root (Legacy Fallback)

Place gcp-oauth.keys.json in the project root directory. This still works for local development but is unreliable with npx or global installs.

OAuth Scope Configuration

By default, the server requests a broad scope set for Drive/Docs/Sheets/Slides/Calendar. You can override requested scopes with:

export GOOGLE_DRIVE_MCP_SCOPES="drive.readonly,documents,spreadsheets"

Notes:

• Comma-separated list.
• Values can be full scope URLs or short aliases: drive, drive.file, drive.readonly, documents, spreadsheets, presentations, calendar, calendar.events.
• Changing scopes usually requires re-authentication.

Token Storage

Authentication tokens are stored securely following the XDG Base Directory specification:

| Priority | Location | Configuration | |----------|----------|---------------| | 1 | Custom path | Set GOOGLE_DRIVE_MCP_TOKEN_PATH environment variable | | 2 | XDG Config | $XDG_CONFIG_HOME/google-drive-mcp/tokens.json | | 3 | Default | ~/.config/google-drive-mcp/tokens.json |

Security Notes:

• Tokens are created with secure permissions (0600)
• Never commit tokens to version control
• Tokens auto-refresh before expiration
• Google OAuth apps in "Testing" status have refresh tokens that expire after 7 days (Google's policy)

Usage with Claude Desktop

Add the server to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Using npx (Recommended):

{
  "mcpServers": {
    "google-drive": {
      "command": "npx",
      "args":