Custom Google Drive MCP
This server is a Google Drive MCP interface that provides Claude.ai-compatible tools for managing files and folders across personal and shared drives. Its capabilities include:
Search & Discovery
Search files using Google Drive query operators with filtering and pagination
List recently modified files and browse folder/shared drive contents
Retrieve detailed file metadata
Reading & Downloading
Extract text from Google Docs, Sheets, Slides, Office files (.docx/.xlsx/.pptx), PDFs, and images
Download raw file bytes as base64 (up to 25 MB), with export format selection for native Google types (e.g., Docs→PDF, Sheets→CSV)
Creation & Import
Create new files with text or base64 binary content (or fetch from a URL), with optional auto-conversion to Google native formats
Create new folders
Import Markdown, DOCX, HTML, RTF, or ODT files as native Google Docs
Initiate resumable upload sessions for large files (bypassing MCP transport limits)
File Management
Update file metadata: rename, move, trash, star, add descriptions, or custom properties
Copy files to new locations
Permissions & Sharing
View detailed permissions and check public access status
Generate shareable links
Grant, update, revoke, or batch-grant permissions, and transfer ownership
Set high-level link-sharing settings (anyone-with-link, copy restrictions, writer-can-share)
Authentication
Manually trigger Google OAuth 2.0 if needed (OAuth 2.1 mode handles auth automatically)
Provides tools for searching, reading, creating, and managing files and folders on Google Drive, including metadata retrieval, content reading/downloading, file creation with MIME-type handling, and permission management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Custom Google Drive MCP find documents about Q4 planning"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
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_filebreak against upstream'ssearch_drive_files,get_drive_file_content,get_drive_file_download_url,create_drive_file. Param names and response shapes also differ.create_drive_filecorrupts binary uploads. Upstream doescontent.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.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 | No Gmail/Calendar/Docs/Sheets/Slides/Forms/Chat/Tasks/Contacts/Search/AppsScript modules in the repo. CLI no longer exposes |
Claude.ai-compatible tool surface | Four overlapping tools renamed and reshaped (see table below). Two new tools ( |
|
|
| Base64 bytes inline, not a temporary URL. Capped at 25 MB by default (env var |
|
|
Mime-aware | If |
Dead-code pruning | Removed unused tier loader, comments helpers, granular-permissions module, dev CLI, and all non-Drive scope/service constants. See |
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 |
| Query-based search across all accessible drives |
|
| Most recently modified files (excludes trashed) |
|
| Single-file metadata by ID |
|
| Extract text from Docs/Sheets/PDF/Office natively |
|
| Raw bytes as base64 |
|
| Create file or folder; auto-converts to Google native unless |
|
Additional tools preserved from upstream (10 tools)
list_drive_items— list children of a foldercreate_drive_folder— dedicated folder creationupdate_drive_file— metadata only (rename/move/trash), not contentimport_to_google_doc— import MD/DOCX/TXT/HTML/RTF/ODT and convert to a native Google Doccopy_drive_fileget_drive_file_permissions,check_drive_file_public_accessget_drive_shareable_link,manage_drive_access,set_drive_file_permissions
Migration from upstream tool names
Upstream | This fork |
|
|
|
|
|
|
|
|
Setup
1. Prerequisites
Python 3.10+ (
.python-versionpins the exact minor version uv will fetch)uv package manager — install via
curl -LsSf https://astral.sh/uv/install.sh | shA 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:
openidhttps://www.googleapis.com/auth/userinfo.emailhttps://www.googleapis.com/auth/userinfo.profilehttps://www.googleapis.com/auth/drivehttps://www.googleapis.com/auth/drive.readonlyhttps://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/oauth2callbackSave the Client ID and Client Secret — you'll paste them into
.envnext.
3. Configure .env
cp env.example .envFor 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=trueIf
WORKSPACE_EXTERNAL_URLis unset the OAuth callback URL is derived from request headers and can drift from what's registered in GCP, causingredirect_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 sync5. Verify
uv run main.py --transport streamable-httpExpected output:
Custom Google Drive MCP Server
Transport: streamable-http
URL: http://localhost:8000
OAuth Callback: http://localhost:8000/oauth2callback
...
Ready for MCP connectionsThe server listens on http://localhost:8000/mcp.
Run locally
HTTP transport (recommended)
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-httpConnect 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 toolsStdio 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_credsRun:
uv run main.py --single-userWire 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:
Deploy to Railway (see below) — set
WORKSPACE_EXTERNAL_URL=https://<service>.up.railway.app.Tunnel localhost over ngrok / Cloudflare Tunnel for testing:
ngrok http 8000 # copy the https://<id>.ngrok-free.app URL it printsThen in
.env:WORKSPACE_EXTERNAL_URL=https://<id>.ngrok-free.app GOOGLE_OAUTH_REDIRECT_URI=https://<id>.ngrok-free.app/oauth2callbackAnd add
https://<id>.ngrok-free.app/oauth2callbackto 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/mcppath — 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.comgoogleapis.com

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 --buildEquivalent 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-mcpSet these in Railway service variables (see env.example):
GOOGLE_OAUTH_CLIENT_ID,GOOGLE_OAUTH_CLIENT_SECRETWORKSPACE_EXTERNAL_URL=https://<service>.up.railway.appMCP_ENABLE_OAUTH21=trueWORKSPACE_MCP_STATELESS_MODE=trueWORKSPACE_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 matchFor 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 |
| The URI in |
| OAuth consent screen isn't published or your Google account isn't in the test-users list. |
| Step 2a was skipped. The server prints a direct enable link in the error message. |
| Change |
| You set both |
| Claude's sandbox egress is blocking the outbound call to |
OAuth callback redirects to the wrong host (e.g. |
|
Provenance
Forked from taylorwilsdon/google_workspace_mcp at commit 5495c83cd3ac503d00cd8015de944c9949cd6443. Upstream LICENSE (MIT) preserved in this directory.
Available Tools
18 toolscheck_drive_file_public_accessCheck Drive File Public AccessARead-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 ContentARead-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 PermissionsBRead-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 MetadataBRead-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 ItemsARead-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 FilesARead-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 AccessADestructive
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 ContentARead-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 FilesBRead-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 PermissionsADestructive
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:
You need to re-authenticate with different credentials
You want to proactively authenticate before using other tools
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 FileBDestructive
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
Scored across 18 tools
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 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.
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.
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
Give Claude only the Google Drive files you choose. Every action logged.
Personal CRM for Claude. Contacts live as plain-text files in your own Google Drive.
Swiss encrypted cloud drive for Claude, ChatGPT and AI agents: search, read and save files.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceConnects AI assistants like Claude to Google Drive, enabling them to browse, read, search, create, and edit files and folders using Google's official API with secure authentication.-
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with Google Drive, supporting file operations like list, search, read, create, update, delete, share, and manage permissions.74MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to search, list, and read files in Google Drive, allowing natural language interaction with your documents and folders.154 npmMIT
- AlicenseAqualityDmaintenanceEnables Claude to search, list, and download files from any Google Drive folder shared with a service account, without OAuth or browser login.3MIT