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.

Auth Server Port Configuration

During OAuth authentication, a local HTTP server is started to receive the callback. By default it tries ports 3000–3004. If those conflict with other services (e.g., a dev server), you can change the starting port:

export GOOGLE_DRIVE_MCP_AUTH_PORT=3100

The server will try 5 consecutive ports starting from the configured value (e.g., 3100–3104).

The callback server binds to the loopback interface and the OAuth redirect URI uses the loopback IP — http://127.0.0.1:<port>/oauth2callback (default range 127.0.0.1:3000–127.0.0.1:3004). Desktop app OAuth clients (the recommended type — see Create OAuth 2.0 Credentials) accept any loopback redirect automatically and need no action. If you instead use a Web application OAuth client, you must register http://127.0.0.1:<port>/oauth2callback for every port in the range as an authorized redirect URI in Google Cloud Console, or authenticati