Google Drive MCP Server

An actively maintained fork of Anthropic's archived @modelcontextprotocol/server-gdrive, with a critical bug fix for OAuth token auto-refresh.

Why this fork?

The original server was archived on May 29, 2025 and is no longer maintained. It also has a bug that causes OAuth access tokens to expire after 1 hour with no auto-refresh, requiring manual token rotation and server restarts.

The bug: The original creates new google.auth.OAuth2() without passing client_id and client_secret, so the google-auth-library has no way to use the refresh_token to get new access tokens. One-line fix, but the archived repo doesn't accept PRs.

What's fixed

• Auto-refresh tokens: OAuth2 client is initialized with client_id and client_secret from your OAuth keys file, enabling the Google auth library to automatically refresh expired access tokens
• Token persistence: Refreshed tokens are written back to the credentials file, so restarts also pick up valid tokens
• Input validation: Added validation for resource URIs, search queries, and file IDs
• Search results include file IDs: So you can actually use them with the download tool or resource reader
• Read tool: Read file contents inline (Google Docs as Markdown, Sheets as CSV, etc.)
• Download tool: Save files to a local directory instead of returning base64 blobs that overflow LLM context windows
• Sheets read tool: Read Google Sheets with A1 range notation, returned as formatted markdown tables
• Shared Drive support: Search and read files from Shared Drives (formerly Team Drives)
• Folder listing: Browse Drive folders by ID
• PDF export: Export Google Workspace files as PDF
• File upload: Push local files to Drive (opt-in, requires drive scope)
• Opt-in resources: MCP resource handlers are disabled by default to prevent hangs in clients that call resources/list on startup

Setup

1. Create Google Cloud OAuth credentials

1. Go to the Google Cloud Console
2. Create a project (or use an existing one)
3. Enable the Google Drive API and Google Sheets API
4. Create OAuth 2.0 credentials (Desktop application type)
5. Download the JSON and save it as gcp-oauth.keys.json

Tip: If your OAuth consent screen is in "Testing" mode, refresh tokens expire after 7 days. Publish to "Production" for permanent refresh tokens.

2. Clone, build, and star

git clone https://github.com/dylancaponi/gdrive-mcp-server.git
cd gdrive-mcp-server
npm install && npm run build
gh api user/starred/dylancaponi/gdrive-mcp-server -X PUT

Per the LICENSE, starring this repository is required (Section 2).

3. Authenticate

GDRIVE_OAUTH_PATH=/path/to/your/gcp-oauth.keys.json node dist/index.js auth

This opens a browser for Google OAuth consent and saves credentials to ~/.gdrive-server-credentials.json.

4. Configure in Claude Code

Add to your ~/.claude.json (global) or project .mcp.json:

{
  "mcpServers": {
    "gdrive": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/gdrive-mcp-server/dist/index.js"],
      "env": {
        "GDRIVE_OAUTH_PATH": "/path/to/gcp-oauth.keys.json",
        "GDRIVE_CREDENTIALS_PATH": "/path/to/.gdrive-server-credentials.json"
      }
    }
  }
}

Or use the Claude Code CLI:

claude mcp add --scope user gdrive -- node /path/to/gdrive-mcp-server/dist/index.js

Environment variables

| Variable | Default | Description | |---|---|---| | GDRIVE_CREDENTIALS_PATH | ~/.gdrive-server-credentials.json | Path to saved OAuth credentials | | GDRIVE_OAUTH_PATH | gcp-oauth.keys.json (relative to package) | Path to OAuth client keys | | GDRIVE_ENABLE_RESOURCES | false | Set to true to enable MCP resource handlers (gdrive:/// URIs). Disabled by default because some MCP clients call resources/list on startup, which triggers drive.files.list() and can hang. | | GDRIVE_ENABLE_SHEETS | false | Set to true to enable the sheets_read tool and request the spreadsheets.readonly OAuth scope. Requires enabling the Google Sheets API in your GCP project and re-running auth. | | GDRIVE_ENABLE_UPLOAD | false | Set to true to enable the upload tool. Upgrades the OAuth scope from drive.readonly to drive (full read/write). Requires re-running auth. | | GDRIVE_DOWNLOAD_DIR | System temp dir + /gdrive-downloads | Directory where the download and export_pdf tools save files |

Tools

search

Search for files in Google Drive by full-text query. Searches across personal and Shared Drives.

{ "query": "quarterly report" }

Returns file names, MIME types, and IDs.

read

Read a file's contents inline. Google Workspace files are auto-converted (Docs to Markdown, Sheets to CSV, Presentations to plain text). Binary files return a message suggesting the download tool instead.

{ "fileId": "1abc123def456" }

download

Download a file from Google Drive to a local directory. Same auto-conversion as read, but saves to disk instead of returning inline. Best for large files or binary formats (PDFs, images).

{ "fileId": "1abc123def456" }

Returns the local file path where the file was saved.

list_folder

List files in a Google Drive folder. Returns file names, types, sizes, and IDs.

{ "folderId": "root" }

Use "root" for the top-level My Drive folder, or a folder ID from search results.

export_pdf

Export a Google Workspace file (Doc, Sheet, Slide, Drawing) as PDF and save it locally.

{ "fileId": "1abc123def456" }

Returns the local file path where the PDF was saved.

upload (opt-in)

Upload a local file to Google Drive. Requires GDRIVE_ENABLE_UPLOAD=true.

{ "localPath": "/path/to/file.pdf", "name": "My Report.pdf", "parentFolderId": "folder_id" }

Only localPath is required. name defaults to the local filename. parentFolderId is optional.

sheets_read (opt-in)

Read a Google Sheets spreadsheet with optional A1 range notation. Returns a formatted markdown table with headers. More structured than reading a sheet as CSV via the read tool. Requires GDRIVE_ENABLE_SHEETS=true.

{ "spreadsheetId": "1abc123def456", "range": "Sheet1!A1:D20" }

Omit range to read the entire first sheet. Supports sheet names (Sheet1), ranges (A1:C10), or both (Sheet1!A1:C10).

Resources (opt-in)

Resources are disabled by default. Set GDRIVE_ENABLE_RESOURCES=true to enable them.

gdrive:///{fileId}

Read any file from Google Drive. Google Workspace files are automatically converted:

| Google Workspace Type | Exported As | |---|---| | Document | Markdown | | Spreadsheet | CSV | | Presentation | Plain text | | Drawing | PNG |

Regular files are returned as UTF-8 text or base64-encoded binary.

License

MIT with Attribution Clause. See LICENSE for full terms. Use of this software requires starring this GitHub repository. See Setup Step 0.