title: "Google Drive MCP Server" date: 2026-08-19 tags:

• project/workspace

• subproject/tools

• type/guide

• area/tech

• date/2026-08-19

Google Drive MCP Server

A local MCP server for Cursor, Claude Code, and Claude Desktop. Through it, the agent searches for and reads files on Google Drive, creates and edits Google Docs and Google Sheets.

When reading, Google Docs are converted to Markdown, spreadsheets to CSV, and presentations to text. Docs can be edited surgically: insert, replace, styles, headings, lists, rename, duplicate. Sheets — values, formats, tabs, rows, and columns. Works with both personal Drive and Shared drives.

Repository: https://github.com/Stillfrozen/gdrive-mcp
Based on wagnerlabs/gdrive-mcp.

OAuth keys live only on your disk. They never end up in git.

Step-by-step setup in Google Cloud (project, API, Desktop OAuth, test users): docs/INSTALL.ru.md

Quick Start

You need Node.js 18+ (20 is better) and a Google account whose Drive you'll be working from.

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

The script installs dependencies, builds the project, and walks you through Google Cloud: project, API, consent screen, Desktop client, browser login. At the end it prints a ready-made snippet for the MCP client.

View the steps without making any changes:

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

If you'd rather click through the Console yourself — the full screen-by-screen breakdown is in docs/INSTALL.ru.md.

Cursor

In ~/.cursor/mcp.json (or .cursor/mcp.json in the project) — only an absolute path:

{
  "mcpServers": {
    "gdrive": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive-mcp/dist/index.js"],
      "env": {
        "GDRIVE_OAUTH_PATH": "/absolute/path/to/gdrive-mcp/credentials/gcp-oauth.keys.json",
        "GDRIVE_CREDENTIALS_PATH": "/absolute/path/to/gdrive-mcp/credentials/.gdrive-server-credentials.json"
      }
    }
  }
}

The env block is optional if the JSON files live in the repository's credentials/. If the file already has other servers, add "gdrive" inside mcpServers without overwriting the rest.

Next, go to Cursor → Settings → MCP → Reload. The gdrive indicator should turn green.

Claude Code CLI

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

--scope user installs the server globally. To remove it: claude mcp remove gdrive.

Claude Desktop

In claude_desktop_config.json:

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

Related MCP server: Google Drive MCP Server

Tools

Reading

Writing: Sheets

Writing: Docs

How values are written to cells

gdrive_update_sheet and gdrive_append_sheet have the value_input_option parameter:

• USER_ENTERED (default) — same as input in the Sheets UI. A formula like =SUM(A1:A10) will execute, numbers and dates will be formatted.

• RAW — as-is. The string =SUM(A1:A10) stays text.

How files are read

gdrive_read_file exports Workspace documents itself:

For the whole spreadsheet (tabs, structure, writing) use gdrive_get_spreadsheet_info and the Sheets write-tools, not gdrive_read_file.

For Doc paragraphs, heading titles, lists, and anchor-based edits use gdrive_get_document_info. The response includes raw text and displayText without the trailing paragraph line break; displayText is usually safer as an anchor. For the fastest Markdown use gdrive_read_file.

Security model

Several layers: MCP annotations, "read first", plus revisions and anchors for Docs, and a current-value check for Sheets.

1. Tool annotations

Each tool declares MCP annotations. The client can ask for confirmation before a destructive operation. See the Destructive / Idempotent columns in the tables above.

2. Read first, then write

The server remembers which spreadsheets and Docs the agent has already opened in this session.

A spreadsheet is considered read after:

• gdrive_read_file (cells as CSV)

• gdrive_get_spreadsheet_info (structure and tabs)

• gdrive_create_sheet (the agent just created the file itself)

A Doc is considered read after:

• gdrive_read_file (Markdown + revision if Google provided it)

• gdrive_get_document_info (tabs or structured text)

• gdrive_create_doc

Any write without that step is rejected:

You must read this spreadsheet before writing to it…

You must read this document before writing to it…

So the agent is less likely to target the wrong file. The list resets on process restart (each MCP session starts fresh).

gdrive_get_file doesn't count here: it's only Drive metadata, not content.

3. Writing to Docs with revision awareness

An edit is tied to the revision the agent read last:

• conflict_mode: "strict" (default) — Docs requiredRevisionId. If the document was edited, the write fails.

• conflict_mode: "merge" — Docs targetRevisionId. Google merges when possible.

The structured content cache lives in the session after gdrive_get_document_info include_content=true. The anchor tools (gdrive_insert_doc_text, gdrive_replace_doc_text, gdrive_update_doc_paragraph_style, gdrive_update_doc_list) use it while the revision is the same. Otherwise the server takes a fresh snapshot.

For targeted text replacement you can pass parameter expected_text: the server checks before sending that the range contains exactly that string.

For the anchored gdrive_delete_doc_text and gdrive_replace_doc_text, the server itself trims only the final paragraph line break when a match hits the end of a tab. The Docs API can't delete a range with a terminal newline segment. Explicit start_index / end_index don't do that: you must exclude the trailing newline yourself.

4. Precondition for Sheets

gdrive_update_sheet has an optional expected_current_values — a two-dimensional array of the same shape as values. The server reads the cells and compares. A mismatch rejects the write, with the actual content in the error.

• Surgical edit (one cell, formula) — pass in expected_current_values.

• Bulk operation (a thousand rows) — don't pass it, or you'll double the requests and hit the quota.

include_previous_values: true returns old the values for audit. If expected_current_values is set, old values are always returned.

Rollback

Doc and Sheets edits show up in the Google Workspace version history. You can roll back there.

No tool deletes an entire file from Drive. Destructive operations only happen inside the Doc and inside the spreadsheet. To delete a file, use the Drive UI.

Configuration

Paths to keys can be overridden with environment variables:

Updating

After git pull, run upgrade. It rebuilds the project and, if setup-manifest.json gained new APIs or scopes, asks you to do auth again:

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

If the manifest hasn't changed, the script just rebuilds and tells you you're good. Cursor picks up dist/ after MCP Reload. No need to re-register the server.

About scope: the server requests full drive, not the narrower drive.file. That's broader than Google's minimum recommendation, but otherwise you couldn't read any available file, write to, or rename existing Docs (rename, duplicate, edits) and write to existing Docs (rename, duplicate, edits). The documents scope is needed for structured reads and batchUpdate.

In Testing status, an external application's refresh token lives for 7 days. Then invalid_grant and you'll need to run npm run auth again. Details and options (Internal / Publish) are in docs/INSTALL.ru.md.

Limitations

• gdrive_create_sheet places the spreadsheet in the root of Drive. You can't pick a folder.

• gdrive_read_file returns CSV from the first tab only for Sheets. Other tabs — via gdrive_get_spreadsheet_info.

• gdrive_read_file always returns Markdown for Docs. Tabs, paragraph boundaries, lists, anchors — gdrive_get_document_info.

• Before changing the formatting and structure of a Doc, first run gdrive_get_document_info include_content=true.

• gdrive_replace_all_doc_text touches the first tab by default. For all tabs you need explicit all_tabs: true.

Development

npm install
npm run dev          # tsx, без сборки
npm run build
npm test
npm run test:live    # живой Google Doc, нужны сохранённые credentials
npm run test:watch

npm run test:live creates a temporary Doc, inserts text through the same stream as MCP, checks it via gdrive_get_document_info, and finally puts the file in the trash.

License

MIT