Google Drive CLI & MCP server

Read access to Google Drive, Docs, and Sheets through two surfaces that share one implementation: a gdrive CLI (the primary surface, built for shell pipelines and AI agents) and an MCP server (stdio). Both authenticate with OAuth2 and call into a transport-agnostic core/ layer.

Requires Node.js >= 24.

This project includes code originally developed by Anthropic, PBC, licensed under the MIT License from this repo, and additional work from isaacphi/mcp-gdrive.

CLI

Build (npm run build), then invoke node dist/bin/gdrive.js <command>. For a bare gdrive command, symlink dist/bin/gdrive.js into any directory on your PATH. Every command accepts a Drive file ID or a Google URL.

gdrive search <query> [--type docs|sheets] [--page-size N] [--page-token TOKEN]
gdrive meta   <fileId|url>
gdrive docs read     <fileId|url> [--section "Heading"] [--json] [--no-images]
gdrive docs headings <fileId|url> [--min N] [--max N]
gdrive docs comments <fileId|url> [--include-resolved]
gdrive docs create   --name "Title" [--from FILE]    (or pipe markdown on stdin)
gdrive docs update   <fileId|url> [--from FILE]       (or pipe markdown on stdin)
gdrive sheets read   <fileId|url> [--range A1:B10] [--csv|--tsv|--json]
gdrive files read    <fileId|url>

docs create/update import Markdown via Drive's native converter. Updates are a full-body replace: text and structure (headings, lists, tables, links) convert, but it does not preserve embedded images or anchored comments. Local image references (![](./x.png)) are stripped before import (they make Drive's importer fail); public image URLs are kept and embedded.

Content is written to stdout so you can pipe or redirect it; structured output is available via --json, and auxiliary notes (e.g. the embedded-image manifest) go to stderr. Binary content is refused on an interactive terminal — redirect it (gdrive files read <id> > out.pdf). Run any command with --help for its flags.

Examples:

gdrive docs read <id> > prd.md                  # whole doc as Markdown
gdrive docs read <id> --section "2. Context"    # just one section
gdrive sheets read <id> --range "'Sheet2'!A1:C9" --tsv
gdrive search "quarterly" --type docs

MCP Components

Tools

• gdrive_search

  • Description: Search for files in Google Drive.
  • Input:
    • query (string): Search query.
    • pageToken (string, optional): Token for the next page of results.
    • pageSize (number, optional): Number of results per page (max 100).
  • Output: Returns structured JSON with file metadata by default. Set MCP_GDRIVE_OUTPUT_FORMAT=text to return a plain text list.

• gdrive_read_file

  • Description: Convenience tool to read contents of a file from Google Drive (legacy behavior preserved).
  • Input:
    • fileId (string): ID of the file to read.
    • url (string, optional): Google Docs/Drive URL with heading anchor (for section extraction).
    • sectionHeading (string, optional): Heading text to extract a section.
  • Output: Returns structured JSON with file metadata and content by default, or plain text with MCP_GDRIVE_OUTPUT_FORMAT=text.

• gdrive_parse_link

  • Description: Parse a Google Docs URL and extract identifiers.
  • Input:
    • url (string): Google Docs URL to parse.
  • Output: Returns fileId, optional headingId, and docType.

• gdrive_get_metadata

  • Description: Fetch file metadata and optional headings for Google Docs.
  • Input:
    • fileId (string): ID of the file to inspect.
    • includeHeadings (boolean, optional): Include headings when file is a Google Doc.
  • Output: Returns file metadata, optional docType, and optional headings list.

• gdrive_list_headings

  • Description: List headings for a Google Doc.
  • Input:
    • fileId (string): ID of the Google Doc to inspect.
    • minLevel (number, optional): Minimum heading level to include (e.g., 2 for H2+).
    • maxLevel (number, optional): Maximum heading level to include (e.g., 3 for up to H3).
  • Output: Returns a headings list (with levels) and file metadata.

• gdrive_read_content

  • Description: Read content explicitly by mode (full or section).
  • Input:
    • fileId (string): ID of the file to read.
    • mode (string, optional): full (default) or section.
    • sectionHeading (string, optional): Required when mode="section".
  • Output: Returns file metadata and content, or a specific section when requested.

• gdrive_download

  • Description: Download content to a local file, returning byte offsets for local paging.
  • Input:
    • fileId (string): ID of the file to read.
    • mode (string, optional): full (default) or section.
    • sectionHeading (string, optional): Required when mode="section".
    • destinationPath (string, optional): Output path or directory for the download.
    • chunkSizeBytes (number, optional): Chunk size for offsets in bytes.
  • Output: Returns file metadata, download path, and byte offsets for local paging.

Download directory

The default download directory can be configured via GDRIVE_DOWNLOAD_DIR. If not set, downloads go to:

~/.mcp-gdrive/downloads

Output format

Tool output format is configured globally via environment variable:

MCP_GDRIVE_OUTPUT_FORMAT=json   # default
MCP_GDRIVE_OUTPUT_FORMAT=text

Agent Workflow (Docs Link)

1. Parse the link with gdrive_parse_link to get fileId and headingId.
2. List headings with gdrive_list_headings (use gdrive_get_metadata for file metadata).
3. Read with gdrive_read_content using mode="section" per heading (avoid full reads for large docs).

Prompts

The server exposes prompt templates to guide agents through common workflows:

• outline_doc (args: url, optional minLevel, maxLevel)
• read_section_by_heading (args: url, sectionHeading)

Sheets

The MCP server reads spreadsheets as CSV via the generic read tools. For range- and tab-aware reads (the Sheets values API), use the CLI's gdrive sheets read. Write operations (creating/updating Docs or Sheets) are not implemented on either surface.

Resources

The server does not currently expose any gdrive:/// resources. Access Drive content via tools.

Setup

Three steps, ~3 minutes. You never edit a .env — credentials are read from the file you download from Google.

1. Install

git clone https://github.com/abanka27/mcp-google-drive.git
cd mcp-google-drive
npm install        # builds automatically (requires Node >= 24)

2. Get Google credentials (one-time, ~2 min)

Each person needs their own OAuth client — credentials can't be shared. Click through these exact pages:

1. Create or pick a project: https://console.cloud.google.com/projectcreate
2. Enable three APIs — click Enable on each:
   • Drive — https://console.cloud.google.com/apis/library/drive.googleapis.com
   • Docs — https://console.cloud.google.com/apis/library/docs.googleapis.com
   • Sheets — https://console.cloud.google.com/apis/library/sheets.googleapis.com
3. OAuth consent screen: https://console.cloud.google.com/apis/credentials/consent Pick Internal if your account offers it. (An External app in "Testing" expires logins every 7 days — add yourself as a test user, or publish it.)
4. Create credentials → OAuth client ID, application type Desktop app: https://console.cloud.google.com/apis/credentials/oauthclient
5. Download the JSON. That single file is all you need.

3. Run setup

npm run setup

This finds the file you just downloaded (in the current directory or ~/Downloads), stores it, opens your browser to sign in once, and links gdrive onto your PATH. If it can't find the file, pass the path explicitly:

node dist/bin/gdrive.js setup ~/Downloads/client_secret_XXXX.json

Done — try it:

gdrive search "" --page-size 3

Credentials and the saved token live in ~/.config/mcp-gdrive ($XDG_CONFIG_HOME/mcp-gdrive), or set GDRIVE_CREDS_DIR to override. The browser prompt only appears on first run; after that the token refreshes silently.

Use with an AI agent (Claude Code skill)

This repo ships a skill at .claude/skills/gdrive/ that teaches an agent the commands and when to reach for them. It loads automatically when you run Claude Code inside this repo. To use it from any directory, copy it into your user skills:

cp -r .claude/skills/gdrive ~/.claude/skills/gdrive

Then ask your agent to read, search, or update Google Docs/Sheets and it will drive gdrive for you.

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.