Google Drive MCP Server

A Model Context Protocol server that gives LLM-powered tools (Claude Code CLI, Cursor, Claude Desktop, etc.) access to Google Drive, Google Docs, and Google Sheets.

Search, list, and read files, including automatic export of Google Docs as Markdown, Sheets as CSV, and Slides as plain text. Create and edit Google Docs with revision-protected text, rich content, native lists, and native tables. Create and edit Google Sheets with bounded range reads, value preconditions, formatting, tab management, and row or column operations. Works with both personal drives and shared drives.

Quick start

1. Guided setup (recommended)

git clone https://github.com/wagnerlabs/gdrive-mcp.git
cd gdrive-mcp
./scripts/install.sh

The setup script installs dependencies, builds the project, and walks you through creating a Google Cloud project, enabling APIs, configuring OAuth, and authenticating. It prints ready-to-copy MCP client config at the end. Run with --dry-run to preview without side effects:

./scripts/install.sh --dry-run

2. Add to your MCP client

Claude Code CLI

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

The --scope user flag installs the server globally, so the MCP server will be available in Claude Code as wagnerlabs-gdrive from any directory you run Claude Code in.

To remove:

claude mcp remove wagnerlabs-gdrive

Cursor

Add to .cursor/mcp.json in any project (or globally):

{
  "mcpServers": {
    "gdrive": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive-mcp/dist/index.js"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "gdrive": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive-mcp/dist/index.js"]
    }
  }
}

Related MCP server: MCP Google Workspace Server

Tools

Read-only tools

Write tools

Sheets

Docs

Value input options

When writing cell values (gdrive_update_sheet, gdrive_append_sheet), the value_input_option parameter controls how values are interpreted:

• USER_ENTERED (default) — Values are parsed as if typed into the Google Sheets UI. Formulas are executed (=SUM(A1:A10)), numbers and dates are formatted automatically.

• RAW — Values are stored exactly as provided. A string like =SUM(A1:A10) is stored as literal text, not executed as a formula.

File format handling

When reading files with gdrive_read_file, Google Workspace documents are automatically exported:

For full spreadsheet access, use gdrive_get_spreadsheet_info to discover tabs and gdrive_get_sheet_values to read an exact bounded range. The returned rectangular values array can be passed directly as expected_current_values to gdrive_update_sheet.

For structured Google Docs reads, use gdrive_get_document_info for compact metadata and tab discovery, then gdrive_get_document_content for bounded pages of paragraphs and native tables. Page tokens contain the document revision and fail with STALE_PAGE_TOKEN if a collaborator changes the document between pages. Structured paragraph responses include both raw text and displayText without the trailing paragraph newline, which is usually the safer anchor to round-trip into Docs write tools. gdrive_read_file remains the fastest way to read a Doc as Markdown.

Table blocks expose a one-based tablePath such as [2]; nested tables extend that path, such as [2,1]. Table cell coordinates are zero-based. Covered coordinates inside merged cells are rejected instead of being silently redirected to another cell.

Safety model

The server applies several layers of protection for both Docs and Sheets, with Docs adding revision-aware write controls and anchor validation on top of the existing Sheets safeguards.

1. Per-tool MCP annotations

Each tool declares its safety characteristics via MCP tool annotations, so MCP clients can prompt the user appropriately before executing destructive operations. See the annotations in the tools tables above.

2. Read-before-write guard

The server tracks which spreadsheets and Docs the agent has actually looked at during the current session.

A spreadsheet is marked as "read" when the agent uses:

• gdrive_read_file (shows cell data as CSV)

• gdrive_get_spreadsheet_info (shows sheet structure and tabs)

• gdrive_get_sheet_values (shows the exact requested cell range)

• gdrive_create_sheet (the agent just created it, so it knows what's there)

A Google Doc is marked as "read" when the agent uses:

• gdrive_read_file (reads the Doc as Markdown and caches the current Docs revision when available)

• gdrive_get_document_info (reads tab metadata or structured paragraph content)

• gdrive_get_document_content (reads a revision-bound page of structured blocks)

• gdrive_create_doc (the agent just created it)

Every write tool checks this session state before executing. If the agent hasn't read the target resource, the call is rejected:

"You must read this spreadsheet before writing to it. Use gdrive_read_file, gdrive_get_spreadsheet_info, or gdrive_get_sheet_values first."

"You must read this document before writing to it. Use gdrive_read_file, gdrive_get_document_info, or gdrive_get_document_content first."

This is intentionally retained: it prevents blind writes and helps catch the wrong target. It is an authorization/awareness guard, not a concurrency guarantee. Preventing stale overwrites requires a revision/version check at write time, like the spreadsheet expected_current_values protection described below.

The read set resets when the server process restarts (every MCP session).

gdrive_get_file is deliberately excluded because it only returns Drive metadata, not sheet structure or document content.

3. Docs revision-aware writes

Docs edits are tied to the revision the agent most recently read explicitly:

• conflict_mode: "strict" is the default. The server checks the current revision immediately before the edit and also sends Docs requiredRevisionId, closing the race between that check and the write. A mismatch fails as STALE_DOCUMENT and requires a reread.

• conflict_mode: "merge" uses Docs targetRevisionId, which lets Google merge the edit with collaborator changes when possible

Internal metadata or anchor-resolution fetches do not silently advance the explicitly observed revision. This matters when a user edits a document after the agent reads it: an internal refresh may help resolve an anchor, but strict mode still refuses to write against the newer unseen revision.

The server also maintains a small session-scoped structured-content cache. Anchor-based tools reuse it when the document revision still matches; otherwise the server fetches a fresh structured snapshot before resolving anchors. Prefer text anchors, table paths, and cell coordinates over raw Docs indices. Explicit indices remain available as an advanced fallback and are validated against editable paragraph ranges where possible.

For targeted Docs text edits, you can also pass expected_text as an optimistic safety check. This verifies the exact text in the resolved range before the write is sent.

For anchor-based gdrive_delete_doc_text and gdrive_replace_doc_text, the server automatically trims only the final paragraph newline when a match reaches the end of the current tab, because the Docs API rejects delete ranges that include the segment-terminal newline. Explicit start_index / end_index edits stay strict and must exclude that trailing newline themselves.

4. Sheets precondition check

gdrive_update_sheet accepts an optional expected_current_values parameter — a 2D array the same shape as values. When provided, the server reads the current cell contents and compares them before writing. If they don't match, the write is refused with STALE_SHEET_VALUES, the range, and the actual values. Read the range again with gdrive_get_sheet_values before retrying.

• For small, targeted edits (changing one cell, fixing a formula): include expected_current_values as a safety net.

• For bulk operations (reformatting dates across 1,000 rows): skip it to avoid doubling API calls and hitting rate limits.

Set include_previous_values: true to include the old values in the response for auditing. When expected_current_values is provided, previous values are always included automatically.

Recovery

Edits made via the Docs and Sheets APIs appear in Google Workspace version history, so users can revert changes if something goes wrong.

No tool can delete an entire Google Doc or spreadsheet file from Google Drive. Destructive operations are limited to structured edits inside a Doc and sheet-level operations inside a spreadsheet. Whole-file deletion still requires the Google Drive UI.

Configuration

Credential paths can be customized via environment variables:

Upgrading

After pulling new changes, run the upgrade script. It rebuilds the project and walks you through any new setup steps (new APIs, scope changes, re-authentication) based on setup-manifest.json:

cd /path/to/gdrive-mcp
git pull
./scripts/upgrade.sh

If no setup changes are needed, ./scripts/upgrade.sh just rebuilds and confirms you're up to date. The MCP server picks up changes on next launch — no need to re-register it.

Scope tradeoff: This server requests full drive rather than drive.file. That is broader than Google's narrowest best practice, but it is required to preserve the current "read any accessible Drive file" behavior and to support rename, duplicate, and write operations on arbitrary existing Docs. The documents scope is required for structured Docs reads and Docs batchUpdate writes.

Notes

• Spreadsheet creation (gdrive_create_sheet) places the new spreadsheet in the user's root Drive folder. Creating in a specific folder is not supported.

• gdrive_read_file exports spreadsheets as CSV from the first sheet only. Use gdrive_get_spreadsheet_info to discover all tabs.

• gdrive_read_file continues to export Google Docs as Markdown. Use gdrive_get_document_info when you need tab metadata, paragraph boundaries, headings, list state, or anchor-friendly ranges.

• For Docs formatting and paragraph structure changes, prefer gdrive_get_document_content so the agent has complete, paginated, revision-aware block and table data.

• gdrive_replace_all_doc_text defaults to the first tab for safety. To replace across every tab, you must set all_tabs: true explicitly.

• Numbered lists use native Google Docs list state. The server will continue a compatible preceding list when requested or fail clearly; it does not simulate numbering by inserting literal digits.

• Live visual inspection and screenshot-based post-write verification are deliberately deferred to a later release. This server verifies structure and revisions through the Docs API, but it does not claim pixel-level layout fidelity.

Development

# Install dependencies
npm install

# Run in dev mode (uses tsx, no build step)
npm run dev

# Build
npm run build

# Run tests
npm test

# Run the live Google Docs smoke test (requires saved credentials)
npm run test:live

# Run tests in watch mode
npm run test:watch

npm run test:live creates a temporary Google Doc, exercises revision-controlled text and structured reads through the MCP server flow, verifies the result, and then trashes the temporary file during cleanup. Set RUN_LIVE_GOOGLE_TESTS=1 if invoking Vitest directly.

License

MIT