mcp-google-drive

Purpose

mcp-google-drive is an MCP (Model Context Protocol) server used to connect to the Google Drive API, allowing AI applications to operate Google Drive in natural language. It is aimed at Claude, Cursor, Codex, and other AI clients, and can view My Drive and shared drives.

Main capabilities

The server provides a total of 21 tools, covering the following areas:

• Search and metadata: find files, view information such as file location and owner.
• Folders and moving: create folders, move files.
• Upload and download: upload content, download files.
• Export: export Google Docs, Sheets, and Slides to other formats (such as Markdown).
• Trash: move files to the recoverable trash, and restore accidentally deleted files.
• Sharing and comments: share files or folders, add comments, list and resolve comments, revoke access permissions.

Several design features:

• Trash first: "delete" by default means the recoverable trash; permanent deletion is a separate tool and will not be selected by mistake.
• Documents remain intact: Docs, Sheets, and Slides are moved, copied, exported, and converted as whole files; the server does not edit text or cells inside documents.
• Optional scopes: drive.readonly covers all read operations; drive.file is limited to files created by the app; the full toolset requires the drive scope.
• Writes are not replayed: retries after network and 5xx errors apply only to reads; copying, uploading, or creating folders will not be executed repeatedly after an uncertain failure.

How to use

Requires Node.js 20+ and a Google account. No credentials are needed during installation; the server can be connected from the conversation.

Basic process:

1. Add the server to the AI application.
2. Say "connect Google Drive"; the assistant will guide you through creating an OAuth client and approving access, with no need to edit configuration files.
3. Start by asking read-only questions, for example: find the project roadmap document in my Drive, export it as Markdown, and summarize it.

In the desktop app: open Settings → MCP servers, select Add server, select STDIO, enter the command npx -y @a1-x-tech/mcp-google-drive@latest and the environment variables GOOGLE_DRIVE_CLIENT_ID, GOOGLE_DRIVE_CLIENT_SECRET, and GOOGLE_DRIVE_REFRESH_TOKEN. Save and restart.

In the IDE extension: open the gear menu → MCP servers, select Add server, select STDIO, and enter the same command and environment variables. Save and restart the extension.

For the command-line method, refer to the Codex MCP documentation and the Claude Code MCP documentation.

The current official path for Claude Desktop is Settings → Extensions. For custom desktop extensions, you can open Advanced settings → Extension Developer → Install Extension…, select the .mcpb file, and follow the prompts. This repository currently publishes an npm stdio package and does not include a .mcpb package. For Claude Desktop versions that still support local configuration, you can use a JSON stdio configuration as a fallback, saved to macOS's ~/Library/Application Support/Claude/claude_desktop_config.json or Windows' %APPDATA%\Claude\claude_desktop_config.json.

Cursor: on macOS/Linux's ~/.cursor/mcp.json or Windows' %USERPROFILE%\.cursor\mcp.json Add the configuration in.

VS Code: Run MCP: Open User Configuration and add the configuration, then check with MCP: List Servers.

Connect from a conversation (recommended)

After saying "connect Google Drive", the assistant runs the following flow:

• setup_instructions prints a checklist: create or select a Google Cloud project, enable the Google Drive API, configure the consent screen, and create a Desktop app OAuth client.
• Download that client's JSON ("Download JSON") and provide the path to the assistant—set_client stores it with owner-only permissions. The secret never passes through the conversation.
• start_login returns a Google consent link. Open it locally and approve; the code returns through a one-time listener on 127.0.0.1 (PKCE), without going through the chat.
• finish_login exchanges the code and saves the token to ~/.config/mcp-google-drive/credentials.json(permissions 0600), and verifies it with a real Google Drive API call.

The token is re-read on every call, so the connection takes effect immediately without restarting the AI app. auth_status shows the connection status, and logout revokes and deletes the credentials.

Environment variables (CI, unattended setup)

1. Create or select a Google Cloud project and enable the Google Drive API.
2. Configure the OAuth consent screen and create a Desktop app OAuth client.
3. Authorize the Google account the server should operate on. When "Use your own OAuth credentials" is enabled, the OAuth 2.0 Playground can obtain a refresh token.

Scope selection:

• https://www.googleapis.com/auth/drive.readonly: read-only tools, including search, metadata, download, export, and shared drive listing.
• https://www.googleapis.com/auth/drive.file: limited to files created or opened by this app, suitable for upload and organization flows for app-owned files.
• https://www.googleapis.com/auth/drive: Complete toolset, including sharing, trash, deletion, and comments for any file.

The server uses the scopes from when the refresh token was issued; calls beyond those scopes fail with an insufficientPermissions error.

OAuth refresh tokens in testing mode may expire after seven days. For long-term access, publish an OAuth app, or use an Internal app in a Workspace domain. Treat the client secret and refresh token as passwords.

All variables are optional—when no variables are set, the server connects from the conversation. Provide the OAuth trio or an access token. With no credentials at all, the server still starts and completes the MCP handshake; the first tool call replies with the specific variables that need to be set, rather than dying.

When to use

• Find and read files: find last quarter's budget spreadsheet and show its location and owner; export the project brief as Markdown and summarize open questions; download the signed contract PDF to the reports folder.
• Organize and transfer content: create a "2026 Reports" folder and move monthly reports into it; upload meeting notes and convert them to a Google Doc; copy a proposal template and rename the copy for a new client.
• Share and discuss: share a folder with a teammate as a commenter and add a note; list unresolved comments on a design doc and resolve the ones already handled; revoke an external contractor's access to the archive.
• Clean up carefully: move outdated drafts to the trash and restore one deleted by mistake; permanently delete a test upload folder after confirming; show the contents of the trash before purging.

Limitations

• Everything in Drive (including folders and shared drive items) is a file with an id. Names are not unique, tools operate by id, duplicate names are legal, and it is best to search before creating.
• "Delete" means trash: recoverable, and Google automatically purges after about 30 days. Permanent deletion bypasses the trash and deletes the folder subtree along with it, in a separate tool.
• Google Docs, Sheets, and Slides are moved, copied, shared, exported, and converted as whole units. The server has no tools for editing text within a Doc or cells within a Sheet.
• The built-in upload limit is 5 MB (larger files use a resumable session via raw_request), and the export limit is 10 MB (per the Drive API). Comments created via the API cannot be anchored to a specific paragraph within a Doc.
• AI clients control confirmation prompts. The server marks read, write, and destructive tools so clients can distinguish inspection from actual changes.
• Google Drive requires OAuth 2.0; an API key is not enough.
• Requests go to Google Drive. The local server refreshes the Google OAuth token and calls the Drive API. Its anonymous telemetry includes an installation ID, package version, AI client and platform version, and tool names—never OAuth tokens, file contents, tool parameters, or prompts. Set ASKADS_TELEMETRY=0 to opt out.
• Google imposes quotas and size limits. On 429 the server uses backoff; reads also retry after network and 5xx errors, while writes are not replayed after an uncertain failure.
• Local file handling is cautious. Downloads are saved only to absolute paths and refuse to overwrite existing files unless asked; text content returned inline is capped at 100 KB.
• No background polling. The server runs only when called; it does not monitor Drive between requests. If the AI app supports scheduled tasks, it can check for changes periodically.