Skip to main content
Glama
Custom Google Drive MCP

Custom Google Drive MCP

Custom Google Drive MCP Server

A slimmed-down fork of taylorwilsdon/google_workspace_mcp that exposes only the Drive tool surface, with the four overlapping tools renamed and reshaped to match the Claude.ai Google Drive connector contract. Drop-in compatible with skills/scripts written against Claude.ai's built-in Drive tools.

Why this exists

The upstream server is a great general-purpose Workspace MCP, but three things made it unsuitable for drop-in use as a Claude.ai Drive connector replacement:

  1. Tool surface doesn't match Claude.ai's Drive connector. Skills written against Claude.ai's built-in search_files, read_file_content, download_file_content, create_file break against upstream's search_drive_files, get_drive_file_content, get_drive_file_download_url, create_drive_file. Param names and response shapes also differ.

  2. create_drive_file corrupts binary uploads. Upstream does content.encode("utf-8") regardless of mime type, so passing a base64-encoded xlsx or pptx results in a Drive file whose bytes are the literal base64 ASCII string — not the decoded binary.

  3. It bundles 11 other Google services (Gmail, Calendar, Docs, Sheets, Slides, Forms, Chat, Tasks, Contacts, Search, Apps Script) that inflate the OAuth consent surface, deploy size, and auth blast radius if you only need Drive.

Related MCP server: MCP Google Drive Server

What's different vs upstream

Change

Effect

Drive-only SERVICE_MODULES (main.py)

No Gmail/Calendar/Docs/Sheets/Slides/Forms/Chat/Tasks/Contacts/Search/AppsScript modules in the repo. CLI no longer exposes --tools, --tool-tier, --permissions.

Claude.ai-compatible tool surface

Four overlapping tools renamed and reshaped (see table below). Two new tools (list_recent_files, get_file_metadata) added to complete the surface.

search_files / list_recent_files return JSON

{"files": [...], "nextPageToken": "..."} with id, name, title, mimeType, parentId, fileSize, modifiedTime, webViewLink per item — directly consumable by automation.

download_file_content returns EmbeddedResource blob

Base64 bytes inline, not a temporary URL. Capped at 25 MB by default (env var DOWNLOAD_FILE_CONTENT_MAX_MB); over-limit returns a descriptive error pointing to read_file_content / shareable link as alternatives.

create_file auto-converts source MIME types to Google native

text/csv → Sheet, text/markdown/text/html/docx → Doc, xlsx → Sheet, pptx → Slides. Pass disableConversionToGoogleType: true to store as-is.

Mime-aware content encoding (create_file)

If mimeType starts with text/ or is one of application/{json,xml,javascript,yaml,x-yaml} → UTF-8 encode the string. Otherwise → treat content as base64 and decode to bytes. Resumable upload chunked at 5 MB.

Dead-code pruning

Removed unused tier loader, comments helpers, granular-permissions module, dev CLI, and all non-Drive scope/service constants. See Provenance for the upstream commit.

The OAuth machinery (Google provider, scopes, session store, callback handling, middleware), core/ server scaffold, attachment storage, http_utils, tool registry, and gdrive/drive_helpers.py are functionally identical to upstream — just trimmed of references to services this fork doesn't ship.

Drive tools available

Claude.ai-compatible surface (6 tools — match the built-in Drive connector)

Tool

Purpose

Key params

search_files

Query-based search across all accessible drives

query, page_size, page_token

list_recent_files

Most recently modified files (excludes trashed)

page_size, page_token

get_file_metadata

Single-file metadata by ID

fileId

read_file_content

Extract text from Docs/Sheets/PDF/Office natively

fileId

download_file_content

Raw bytes as base64 EmbeddedResource (capped at DOWNLOAD_FILE_CONTENT_MAX_MB, default 25 MB)

fileId, export_format

create_file

Create file or folder; auto-converts to Google native unless disableConversionToGoogleType=true

title, content (b64 for binary), mimeType, parentId, fileUrl, disableConversionToGoogleType

Additional tools preserved from upstream (10 tools)

  • list_drive_items — list children of a folder

  • create_drive_folder — dedicated folder creation

  • update_drive_file — metadata only (rename/move/trash), not content

  • import_to_google_doc — import MD/DOCX/TXT/HTML/RTF/ODT and convert to a native Google Doc

  • copy_drive_file

  • get_drive_file_permissions, check_drive_file_public_access

  • get_drive_shareable_link, manage_drive_access, set_drive_file_permissions

Migration from upstream tool names

Upstream

This fork

search_drive_files

search_files (JSON response, includes parentId)

get_drive_file_content

read_file_content (fileId, was file_id)

get_drive_file_download_url

download_file_content (returns EmbeddedResource blob, was URL string; param fileId, was file_id)

create_drive_file

create_file (params: title/parentId/mimeType, was file_name/folder_id/mime_type)


Setup

1. Prerequisites

  • Python 3.10+ (.python-version pins the exact minor version uv will fetch)

  • uv package manager — install via curl -LsSf https://astral.sh/uv/install.sh | sh

  • A Google account you'll authorize the server with

  • A Google Cloud project (free tier is fine)

2. Google Cloud configuration (one-time)

In console.cloud.google.com, select or create a project, then:

a. Enable the Drive API APIs & Services → Library → search "Google Drive API" → Enable.

b. Configure the OAuth consent screen APIs & Services → OAuth consent screen.

  • User type: External (or Internal if you have a Workspace org).

  • Add yourself under Test users so you can authorize while the consent screen is in testing mode.

  • Add scopes:

    • openid

    • https://www.googleapis.com/auth/userinfo.email

    • https://www.googleapis.com/auth/userinfo.profile

    • https://www.googleapis.com/auth/drive

    • https://www.googleapis.com/auth/drive.readonly

    • https://www.googleapis.com/auth/drive.file

c. Create an OAuth 2.0 Client ID APIs & Services → Credentials → Create credentials → OAuth client ID.

  • Application type: Web application (not "Desktop app").

  • Authorized redirect URIs: http://localhost:8000/oauth2callback

  • Save the Client ID and Client Secret — you'll paste them into .env next.

3. Configure .env

cp env.example .env

For the recommended local setup (HTTP transport + OAuth 2.1 + in-memory session storage, matches the Railway production config):

# Google OAuth client (from step 2c)
GOOGLE_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret
GOOGLE_OAUTH_REDIRECT_URI=http://localhost:8000/oauth2callback

# Transport
WORKSPACE_MCP_TRANSPORT=streamable-http
WORKSPACE_MCP_PORT=8000
WORKSPACE_MCP_HOST=0.0.0.0

# Externally-reachable URL — used to build the OAuth callback redirect.
# For plain localhost dev, point this at the same host:port the server binds to.
# Tunnel/Railway setups override this with their public HTTPS URL.
WORKSPACE_EXTERNAL_URL=http://localhost:8000

# Auth mode
MCP_ENABLE_OAUTH21=true
WORKSPACE_MCP_STATELESS_MODE=true

If WORKSPACE_EXTERNAL_URL is unset the OAuth callback URL is derived from request headers and can drift from what's registered in GCP, causing redirect_uri_mismatch. Always set it explicitly to the URL where this MCP is reachable.

For stdio mode (e.g. Claude Desktop), see the alternative recipe under Run locally below.

4. Install dependencies

uv sync

5. Verify

uv run main.py --transport streamable-http

Expected output:

Custom Google Drive MCP Server
  Transport: streamable-http
  URL: http://localhost:8000
  OAuth Callback: http://localhost:8000/oauth2callback
  ...
Ready for MCP connections

The server listens on http://localhost:8000/mcp.


Run locally

Matches the Railway production setup. Use this for Claude.ai, MCP Inspector, or any client that speaks streamable-http.

uv run main.py --transport streamable-http

Connect a client to http://localhost:8000/mcp. The client triggers the OAuth flow on the first tool call — your browser opens, you authorize, the access token lives in server memory for the session.

Smoke test with MCP Inspector:

npx @modelcontextprotocol/inspector
# Transport: streamable-http
# URL: http://localhost:8000/mcp
# Click Connect → do the OAuth handshake → List tools

Stdio transport (Claude Desktop, etc.)

Stdio mode talks the MCP protocol over stdin/stdout instead of HTTP, so the OAuth callback uses a tiny standalone server on port 8000 that auto-starts when needed.

Override .env with:

# Drop or comment these out for stdio mode:
# WORKSPACE_MCP_TRANSPORT=streamable-http
# MCP_ENABLE_OAUTH21=true
# WORKSPACE_MCP_STATELESS_MODE=true

# Required: pin to one Google account
USER_GOOGLE_EMAIL=you@example.com
MCP_SINGLE_USER_MODE=1

# Where credentials persist between runs
WORKSPACE_MCP_CREDENTIALS_DIR=./store_creds

Run:

uv run main.py --single-user

Wire into a Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "custom-gdrive": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/this/repo/main.py", "--single-user"]
    }
  }
}

Connect to Claude.ai (web)

Claude.ai's custom connector requires a public HTTPS URL — http://localhost won't work because Anthropic's edge servers, not your browser, fetch the MCP endpoint. Two paths:

  1. Deploy to Railway (see below) — set WORKSPACE_EXTERNAL_URL=https://<service>.up.railway.app.

  2. Tunnel localhost over ngrok / Cloudflare Tunnel for testing:

    ngrok http 8000
    # copy the https://<id>.ngrok-free.app URL it prints

    Then in .env:

    WORKSPACE_EXTERNAL_URL=https://<id>.ngrok-free.app
    GOOGLE_OAUTH_REDIRECT_URI=https://<id>.ngrok-free.app/oauth2callback

    And add https://<id>.ngrok-free.app/oauth2callback to the GCP OAuth client's authorized redirect URIs. Restart the MCP server after editing .env.

In claude.ai → Settings → Connectors → Add custom connector:

  • Name: anything

  • Remote MCP server URL: https://<your-external-url>/mcp (don't omit the /mcp path — POST to / returns 405)

Click Connect. The OAuth flow opens in a new tab; authorize with the Google account you added under GCP Console → OAuth consent screen → Test users.

Whitelist googleapis.com in Claude.ai's network egress allowlist. Claude's analysis sandbox can't reach arbitrary hosts by default, so any tool call that streams file bytes from the sandbox to Google Drive (e.g. uploading a generated xlsx via create_file) silently fails until you allow it. In claude.ai → Settings → Capabilities → enable Allow network egress, leave the dropdown on Package managers only, and add these under Additional allowed domains:

  • *.googleapis.com

  • googleapis.com

Claude egress allowlist with *.googleapis.com and googleapis.com added

Without this, the connector itself works (Claude → MCP → Drive is fine), but any code execution step that pushes bytes outbound to Google will be blocked by the sandbox firewall, not by the MCP.

Free ngrok URLs change on each restart. Each new URL means re-editing .env and re-adding the redirect URI in GCP. Use a static domain (paid plan) or Cloudflare Tunnel for a stable setup.

Docker

docker compose up --build

Equivalent to the HTTP transport recipe; reads .env from this directory.


Deploy to Railway

The Dockerfile is set up for Railway as-is:

# From the repo root
railway up --service custom-gdrive-mcp

Set these in Railway service variables (see env.example):

  • GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET

  • WORKSPACE_EXTERNAL_URL=https://<service>.up.railway.app

  • MCP_ENABLE_OAUTH21=true

  • WORKSPACE_MCP_STATELESS_MODE=true

  • WORKSPACE_MCP_TRANSPORT=streamable-http

Add https://<service>.up.railway.app/oauth2callback to the GCP OAuth client's authorized redirect URIs.


Smoke-test the binary upload fix

# 1. Round-trip a small pptx
PPTX=/path/to/test.pptx
B64=$(base64 -i "$PPTX")

# 2. Call create_file via MCP inspector or your client with:
#    title="test_binary.pptx"
#    content=$B64
#    mimeType="application/vnd.openxmlformats-officedocument.presentationml.presentation"
#    disableConversionToGoogleType=true   # keep as pptx, don't convert to Slides

# 3. Download the resulting file from Drive
curl -L -o roundtrip.pptx "<webContentLink>"

# 4. Verify
file roundtrip.pptx        # Should report "Microsoft PowerPoint", not "ASCII text"
md5 "$PPTX" roundtrip.pptx # Should match

For a text round-trip (markdown, no base64), pass mimeType="text/markdown" and content=<raw string> — the UTF-8 path kicks in automatically. Add disableConversionToGoogleType=true to keep it as a plain .md file (otherwise the auto-convert path turns it into a Google Doc).


Common gotchas

Symptom

Fix

redirect_uri_mismatch

The URI in .env doesn't exactly match what's registered in GCP. Check protocol (http vs https), port, and path.

Access blocked: This app's request is invalid

OAuth consent screen isn't published or your Google account isn't in the test-users list.

Drive API has not been used in project ... before or it is disabled

Step 2a was skipped. The server prints a direct enable link in the error message.

Port 8000 already in use

Change WORKSPACE_MCP_PORT and update the redirect URI in both .env and the GCP OAuth client.

--single-user is incompatible with OAuth 2.1 mode

You set both MCP_ENABLE_OAUTH21=true and passed --single-user. Pick one mode per the recipes above.

create_file succeeds from a direct MCP client but fails when Claude runs it from code execution

Claude's sandbox egress is blocking the outbound call to *.googleapis.com. Whitelist it under claude.ai → Settings → Capabilities → Network access.

OAuth callback redirects to the wrong host (e.g. 0.0.0.0:8000 or a Railway internal hostname)

WORKSPACE_EXTERNAL_URL isn't set. Point it at the URL the MCP is actually reachable on (http://localhost:8000 locally, the public HTTPS URL in prod).


Provenance

Forked from taylorwilsdon/google_workspace_mcp at commit 5495c83cd3ac503d00cd8015de944c9949cd6443. Upstream LICENSE (MIT) preserved in this directory.

Available Tools

18 tools
check_drive_file_public_accessCheck Drive File Public AccessA
Read-onlyIdempotent

Searches for a file by name and checks if it has public link sharing enabled.

Inputs: file_name (required), user_google_email, drive_id. Returns: result

copy_drive_fileCopy Drive FileA

Creates a copy of an existing Google Drive file.

This tool copies the template document to a new location with an optional new name. The copy maintains all formatting and content from the original file.

Inputs: file_id (required), user_google_email, new_name, parent_folder_id. Returns: result

create_drive_folderCreate Drive FolderA

Creates a new folder in Google Drive, supporting creation within shared drives.

Inputs: folder_name (required), user_google_email, parent_folder_id. Returns: result

create_fileCreate FileA

Creates a new file in Google Drive, supporting creation within shared drives. Accepts either direct content or a fileUrl to fetch the content from.

Inputs: title (required), user_google_email, content, parentId, +3 more. Returns: object

create_resumable_upload_sessionCreate Resumable Upload SessionA

Creates a Google Drive resumable upload session and returns the upload URL.

The caller (e.g. a skill running in claude.ai's sandbox) uses the returned upload_url to PUT raw file bytes directly to Google — bypassing MCP transport limits on large content arguments. Only the short URL travels through MCP; the bytes go straight from the sandbox to Google.

Inputs: title (required), mimeType (required), user_google_email, parentId, +1 more. Returns: object

download_file_contentDownload File ContentA
Read-onlyIdempotent

Downloads a Google Drive file and returns its raw bytes as a base64-encoded blob.

For Google native files (Docs, Sheets, Slides), exports to a useful format:

  • Google Docs -> PDF (default) or DOCX if export_format='docx'

  • Google Sheets -> XLSX (default), PDF if export_format='pdf', or CSV if export_format='csv'

  • Google Slides -> PDF (default) or PPTX if export_format='pptx'

For other files, downloads the original file format.

Size limit: DOWNLOAD_FILE_CONTENT_MAX_MB env var (default 25 MB). Files larger than the limit return an error pointing to read_file_content for text extraction, or a Drive shareable link as a fallback.

Inputs: fileId (required), user_google_email, export_format.

get_drive_file_permissionsGet Drive File PermissionsB
Read-onlyIdempotent

Gets detailed metadata about a Google Drive file including sharing permissions.

Inputs: file_id (required), user_google_email. Returns: result

get_file_metadataGet File MetadataB
Read-onlyIdempotent

Returns metadata for a single Google Drive file by ID.

Inputs: fileId (required), user_google_email. Returns: object

import_to_google_docImport to Google DocA

Imports a file (Markdown, DOCX, TXT, HTML, RTF, ODT) into Google Docs format with automatic conversion.

Google Drive automatically converts the source file to native Google Docs format, preserving formatting like headings, lists, bold, italic, etc. For batch operations, prefer file_path for files on disk so callers do not need to load full file contents into their context.

Inputs: file_name (required), user_google_email, content, file_path, +3 more. Returns: result

list_drive_itemsList Drive ItemsA
Read-onlyIdempotent

Lists files/folders or shared drive containers, supporting shared drives. If drive_id is specified, lists items within that shared drive. folder_id is then relative to that drive (or use drive_id as folder_id for root). If drive_id is not specified, lists items from user's "My Drive" and accessible shared drives (if include_items_from_all_drives is True). Set resource_type to "shared_drives" to list shared drive containers instead of folder contents.

Inputs: user_google_email, folder_id, page_size, page_token, +9 more. Returns: result

list_recent_filesList Recent FilesA
Read-onlyIdempotent

Lists the user's most recently modified files in Google Drive (across all drives the user has access to). Excludes trashed items.

Inputs: user_google_email, page_size, page_token. Returns: object

manage_drive_accessManage Drive AccessA
Destructive

Consolidated tool for managing Google Drive file and folder access permissions.

Supports granting, batch-granting, updating, revoking permissions, and transferring file ownership -- all through a single entry point.

Inputs: file_id (required), action (required), user_google_email, share_with, +10 more. Returns: result

read_file_contentRead File ContentA
Read-onlyIdempotent

Retrieves the content of a specific Google Drive file by ID, supporting files in shared drives.

• Native Google Docs, Sheets, Slides → exported as text / CSV. • Office files (.docx, .xlsx, .pptx) → unzipped & parsed with std-lib to extract readable text. • PDFs → text extracted with pypdf when possible; scanned/image-only PDFs fall back to a download hint. • Images → returned as base64 with MIME metadata for multimodal clients. • Any other file → downloaded; tries UTF-8 decode, else notes binary.

Inputs: fileId (required), user_google_email. Returns: result

search_filesSearch FilesB
Read-onlyIdempotent

Searches for files and folders within a user's Google Drive, including shared drives.

Inputs: query (required), user_google_email, page_size, page_token, +6 more. Returns: object

set_drive_file_permissionsSet Drive File PermissionsA
Destructive

Sets file-level sharing settings and controls link sharing for a Google Drive file or folder.

This is a high-level tool for the most common permission changes. Use this to toggle "anyone with the link" access or configure file-level sharing behavior. For managing individual user/group permissions, use share_drive_file or update_drive_permission instead.

Inputs: file_id (required), user_google_email, link_sharing, writers_can_share, +1 more. Returns: result

start_google_authStart Google AuthA

Manually initiate Google OAuth authentication flow.

NOTE: This is a legacy OAuth 2.0 tool and is disabled when OAuth 2.1 is enabled. The authentication system automatically handles credential checks and prompts for authentication when needed. Only use this tool if:

  1. You need to re-authenticate with different credentials

  2. You want to proactively authenticate before using other tools

  3. The automatic authentication flow failed and you need to retry

In most cases, simply try calling the Google Workspace tool you need - it will automatically handle authentication if required.

Inputs: service_name (required), user_google_email. Returns: result

update_drive_fileUpdate Drive FileB
Destructive

Updates metadata and properties of a Google Drive file.

Inputs: file_id (required), user_google_email, name, description, +8 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 18 tools

    Disambiguation4/5

    Most tools have distinct purposes, with clear descriptions differentiating overlapping functions like multiple permission tools and content retrieval methods. However, some pairs (e.g., create_file vs import_to_google_doc, download_file_content vs read_file_content) could cause confusion despite descriptive names.

    Naming Consistency3/5

    Naming follows a general verb_noun pattern but mixes styles: some use 'get', some 'list', some 'read', and 'manage_drive_access' is generic. Inconsistencies like 'create_file' vs 'create_drive_folder' and 'start_google_auth' break the pattern, making the set somewhat predictable but not fully uniform.

    Tool Count5/5

    With 18 tools, the server covers a broad range of Google Drive operations without being overwhelming. Each tool addresses a distinct need (CRUD, permissions, search, auth, upload), and the count feels well-scoped for the domain.

    Completeness2/5

    The tool set lacks a basic delete/trash operation, which is a critical gap for file management. While it covers creation, copying, updating, permissions, and reading, the absence of deletion means agents cannot complete lifecycle workflows, leading to potential failures.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to search, list, and read files in Google Drive, allowing natural language interaction with your documents and folders.
      154 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables Claude to search, list, and download files from any Google Drive folder shared with a service account, without OAuth or browser login.
      3
      MIT