# Google Drive Mcp

> 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 through a standardized interface.

- **Type:** MCP server
- **Install:** `agentstack add mcp-piotr-agier-google-drive-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [piotr-agier](https://agentstack.voostack.com/s/piotr-agier)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [piotr-agier](https://github.com/piotr-agier)
- **Source:** https://github.com/piotr-agier/google-drive-mcp
- **Website:** https://www.npmjs.com/package/@piotr-agier/google-drive-mcp

## Install

```sh
agentstack add mcp-piotr-agier-google-drive-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://console.cloud.google.com)
- 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:

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

2. 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
   ```

3. 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
   ```

2. **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
   ```

2. **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:

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

```json
{
  "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:

```json
{
  "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)
```bash
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:

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

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

```json
{
  "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):
```json
{
  "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:
```json
{
  "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

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

Or with environment variables:

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

```json
{
  "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](https://github.com/piotr-agier)
- **Source:** [piotr-agier/google-drive-mcp](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-piotr-agier-google-drive-mcp
- Seller: https://agentstack.voostack.com/s/piotr-agier
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.