Google Drive Mcp

Google Drive MCP Server

A Model Context Protocol (MCP) server that provides secure integration with Google Drive, Docs, Sheets, Slides, and Calendar. It allows Claude Desktop and other MCP clients to manage files in Google Drive and calendar events through a standardized interface.

Features

• Multi-format Support: Work with Google Docs, Sheets, Slides, Calendar, and regular files
• File Management: Create, update, delete, rename, move, copy, upload, and download files and folders
• Advanced Search: Search across your entire Google Drive
• Shared Drives Support: Full access to Google Shared Drives (formerly Team Drives) in addition to My Drive
• Folder Navigation: List and navigate through folder hierarchies with path support (e.g., /Work/Projects)
• Google Docs Editing: Surgical text insertion/deletion, table management, image embedding, comments, and rich formatting
• Google Calendar: Full calendar management — list calendars, create/update/delete events, Google Meet integration
• MCP Resource Protocol: Files accessible as MCP resources for reading content
• Secure Authentication: OAuth 2.0 with automatic token refresh

Example Usage

This MCP server enables powerful file management workflows through natural language:

1. Document Creation and Organization

Create a new Google Doc called "Project Plan" in the folder /Work/Projects
with an outline for our Q1 initiatives including milestones and deliverables.

2. File Search and Organization

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:

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

1. Set up credentials:

```bash # Copy the example file cp gcp-oauth.keys.example.json gcp-oauth.keys.json

# Edit gcp-oauth.keys.json with your OAuth client ID ```

1. Authenticate (optional):

``bash 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:

```bash # Using npx npx @piotr-agier/google-drive-mcp auth

# Or using local installation npm run auth ```

1. Verify token location:

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

Building the Docker Image

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

``bash npm install npm run build ``

1. Build the Docker image:

``bash 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:/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](#4-create-oauth-20-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:/oauth2callback for every port in the range as an authorized redirect URI in Google Cloud Console, or authentication fails with redirect_uri_mismatch.

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)

Runtime Configuration (CLI args or env vars)

Configure timeouts and retry behavior via CLI flags (preferred) or environment variables. CLI flags take priority over env vars.

> Scope: these settings currently apply to the createGoogleDoc content-insertion > call (the documents.batchUpdate that was prone to silent timeouts). They are not > yet wired into every Google API call.

CLI flags

| Flag | Default | Description | | ------------------------- | ------- | --------------------------------------------------------------------------- | | --api-timeout= | 120000 | Per-attempt timeout for the retry-wrapped call; 0 disables the timeout | | --retry-max= | 3 | Max retry attempts on retryable errors (429/503/504, timeouts, network); 0 disables retries | | --retry-base-delay= | 1000 | Base delay for exponential backoff (capped at 30s, with jitter) |

Environment variables (fallback)

• GOOGLE_DRIVE_MCP_API_TIMEOUT
• GOOGLE_DRIVE_MCP_RETRY_MAX
• GOOGLE_DRIVE_MCP_RETRY_BASE_DELAY

Example (Claude Desktop config)

{
  "mcpServers": {
    "google-drive": {
      "command": "npx",
      "args": ["@piotr-agier/google-drive-mcp", "--api-timeout=180000", "--retry-max=5"]
    }
  }
}

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": ["@piotr-agier/google-drive-mcp"],
      "env": {
        "GOOGLE_DRIVE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
      }
    }
  }
}

Using Local Installation:

{
  "mcpServers": {
    "google-drive": {
      "command": "node",
      "args": ["/absolute/path/to/google-drive-mcp/dist/index.js"],
      "env": {
        "GOOGLE_DRIVE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
      }
    }
  }
}

Note: Replace /path/to/your/gcp-oauth.keys.json with the actual path to your OAuth credentials file.

Streamable HTTP Transport

By default the server uses stdio transport (for local MCP clients like Claude Desktop). You can also run it as an HTTP server using the Streamable HTTP transport, which enables remote/hosted deployments and shared gateways.

Starting in HTTP mode

google-drive-mcp start --transport http --port 3100 --host 127.0.0.1

Or with environment variables:

MCP_TRANSPORT=http MCP_HTTP_PORT=3100 MCP_HTTP_HOST=127.0.0.1 google-drive-mcp start

CLI flags take priority over environment variables.

| CLI Flag | Env Var | Default | Description | |----------|---------|---------|-------------| | --transport | MCP_TRANSPORT | stdio | stdio or http | | --port | MCP_HTTP_PORT | 3100 | HTTP listen port | | --host | MCP_HTTP_HOST | 127.0.0.1 | HTTP bind address |

The HTTP endpoint is POST /mcp for JSON-RPC requests, GET /mcp for SSE streaming, and DELETE /mcp to close a session. After the initial initialize request, all subsequent requests must include the mcp-session-id header returned in the initialize response.

When binding to 127.0.0.1 (default), DNS rebinding protection is automatically enabled. For remote deployments (0.0.0.0), use service account or external token authentication and ensure the endpoint is behind a reverse proxy with TLS. Without authentication and TLS, anyone who can reach the port gets full access to the configured Google Drive account.

MCP client configuration (HTTP)

{
  "mcpServers": {
    "google-drive": {
      "url": "http://localhost:3100/mcp"
    }
  }
}

Available Tools

Search and Navigation

• search - Search for files across Google Drive
• query: Search terms (or raw Drive API query when rawQuery=true)
• pageSize: Number of results per page (optional, default 50, max 100)
• pageToken: Pagination token for next page (optional)
• rawQuery: Pass query directly to the Drive API — enables operators like modifiedTime, createdTime, mimeType, name contains, etc. (optional)

• listFolder - List contents of a folder
• folderId: Folder ID (optional, defaults to root)
• pageSize: Number of results (optional, max 100)
• pageToken: Pagination token (optional)

• listSharedDrives - List available Google Shared Drives
• pageSize: Number of drives to return (optional, default 50, max 100)
• pageToken: Pagination token (optional)

File Management

• createTextFile - Create a text or markdown file
• name: File name (must end with .txt or .md)
• content: File content
• parentFolderId: Parent folder ID (optional)

• updateTextFile - Update existing text file
• fileId: File ID to update
• content: New content
• name: New name (optional)

• deleteItem - Move a file or folder to trash (not a permanent deletion - items can be restored from Google Drive trash)
• itemId: Item ID to move to trash

• renameItem - Rename a file or folder
• itemId: Item ID to rename
• newName: New name

• **mo

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: piotr-agier
• Source: piotr-agier/google-drive-mcp
• License: MIT
• Homepage: https://www.npmjs.com/package/@piotr-agier/google-drive-mcp

Install and usage instructions live in the source repository linked above.