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

• Projekt/workspace

• Unterprojekt/tools

• Typ/guide

• Bereich/tech

• Datum/2026-08-19

Google Drive MCP Server

Ein lokaler MCP-Server für Cursor, Claude Code und Claude Desktop. Darüber sucht und liest der Agent Dateien auf Google Drive, erstellt und bearbeitet Google Docs und Google Sheets.

Google Docs werden beim Lesen in Markdown umgewandelt, Tabellen in CSV, Präsentationen in Text. Docs lassen sich punktuell bearbeiten: Einfügen, Ersetzen, Stile, Überschriften, Listen, Umbenennen, Duplizieren. Sheets – Werte, Formate, Tabs, Zeilen und Spalten. Funktioniert sowohl mit dem persönlichen Drive als auch mit Shared drives.

Repository: https://github.com/Stillfrozen/gdrive-mcp
Basierend auf wagnerlabs/gdrive-mcp.

OAuth-Schlüssel liegen nur auf Ihrer Festplatte. Sie gelangen nicht in Git.

Schritt-für-Schritt-Installation in Google Cloud (Projekt, API, Desktop OAuth, test users): docs/INSTALL.ru.md

Schnellstart

Erforderlich sind Node.js 18+ (besser 20) und ein Google-Konto, dessen Drive Sie verwenden möchten.

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

Das Skript installiert Abhängigkeiten, baut das Projekt und führt Sie durch Google Cloud: Projekt, API, Zustimmungsbildschirm, Desktop-Client, Anmeldung im Browser. Am Ende gibt es einen fertigen Ausschnitt für den MCP-Client aus.

Schritte unverändert ansehen:

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

Wenn Sie selbst in der Console klicken möchten – die komplette Erklärung der Screens finden Sie in docs/INSTALL.ru.md.

Cursor

In ~/.cursor/mcp.json (oder .cursor/mcp.json im Projekt) – nur der absolute Pfad:

{
  "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"
      }
    }
  }
}

Der Block env ist nicht erforderlich, wenn die JSON-Dateien in credentials/ des Repos liegen. Wenn die Datei bereits andere Server enthält, fügen Sie "gdrive" in mcpServers ein, ohne den Rest zu überschreiben.

Danach Cursor → Settings → MCP → Reload. Der Indikator gdrive sollte grün werden.

Claude Code CLI

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

--scope user registriert den Server global. Entfernen: 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

Lesen

Schreiben: Sheets

Schreiben: Docs

Wie Werte in Zellen geschrieben werden

gdrive_update_sheet und gdrive_append_sheet haben den Parameter value_input_option:

• USER_ENTERED (Standard) – wie bei der Eingabe in die Sheets-UI. Die Formel =SUM(A1:A10) wird ausgeführt, Zahlen und Daten formatiert.

• RAW – unverändert. Die Zeichenkette =SUM(A1:A10) bleibt Text.

Wie Dateien gelesen werden

gdrive_read_file exportiert Workspace-Dokumente selbst:

Für die gesamte Tabelle (Tabs, Struktur, Schreiben) verwenden Sie gdrive_get_spreadsheet_info und die Sheets-Schreib-Tools, nicht gdrive_read_file.

Für Absätze, Überschriften, Listen und Ankerbearbeitungen im Doc verwenden Sie gdrive_get_document_info. Die Antwort enthält rohes text und displayText ohne abschließenden Absatzumbruch; displayText ist als Anker in der Regel sicherer. Markdown liefert am schnellsten gdrive_read_file.

Sicherheitsmodell

Mehrere Ebenen: MCP-Annotationen, „erst lesen“, für Docs zusätzlich Revision und Anker, für Sheets ein Abgleich der aktuellen Werte.

1. Tool-Annotationen

Jedes Tool deklariert MCP-Annotationen. Der Client kann vor einer destruktiven Operation eine Bestätigung anfordern. Siehe die Spalten Destructive / Idempotent in den obigen Tabellen.

2. Erst lesen, dann schreiben

Der Server merkt sich, welche Tabellen und Docs der Agent in dieser Sitzung bereits geöffnet hat.

Eine Tabelle gilt als gelesen nach:

• gdrive_read_file (Zellen als CSV)

• gdrive_get_spreadsheet_info (Struktur und Tabs)

• gdrive_create_sheet (der Agent hat die Datei gerade selbst erstellt)

Ein Doc gilt als gelesen nach:

• gdrive_read_file (Markdown + Revision, sofern Google sie geliefert hat)

• gdrive_get_document_info (Tabs oder strukturierter Text)

• gdrive_create_doc

Jeder Schreibvorgang ohne diesen Schritt wird abgelehnt:

You must read this spreadsheet before writing to it…

You must read this document before writing to it…

So zielt der Agent seltener auf die falsche Datei. Die Liste wird beim Neustart des Prozesses zurückgesetzt (jede MCP-Sitzung beginnt von Neuem).

gdrive_get_file zählt nicht dazu: Es liefert nur Drive-Metadaten, nicht den Inhalt.

3. Schreiben in Docs mit Revisionsprüfung

Die Bearbeitung ist an die Revision gebunden, die der Agent zuletzt gelesen hat:

• conflict_mode: "strict" (Standard) – Docs requiredRevisionId. Wenn das Dokument inzwischen geändert wurde, schlägt der Schreibvorgang fehl.

• conflict_mode: "merge" – Docs targetRevisionId. Google führt die Änderungen nach Möglichkeit mit fremden Bearbeitungen zusammen.

Der Cache strukturierter Inhalte bleibt in der Sitzung erhalten, nachdem gdrive_get_document_info include_content=true aufgerufen wurde. Anker-Tools (gdrive_insert_doc_text, gdrive_replace_doc_text, gdrive_update_doc_paragraph_style, gdrive_update_doc_list) verwenden ihn, solange die Revision dieselbe ist. Andernfalls erstellt der Server erneut einen Snapshot.

Für gezielte Textersetzungen kann expected_text übergeben werden: Vor dem Senden prüft der Server, ob in dem Bereich genau dieser String steht.

Bei den Anker-Tools gdrive_delete_doc_text und gdrive_replace_doc_text schneidet der Server selbst nur den abschließenden Absatzumbruch ab, wenn die Übereinstimmung am Ende des Tabs endet. Die Docs-API löscht keinen Bereich mit einem terminalen Newline des Segments. Explizite start_index / end_index tun das nicht: Sie müssen das abschließende Newline selbst ausschließen.

4. Vorbedingung für Sheets

gdrive_update_sheet hat einen optionalen Parameter expected_current_values – ein zweidimensionales Array in derselben Form wie values. Der Server liest die Zellen und vergleicht. Bei Abweichung wird der Schreibvorgang abgelehnt; die Fehlermeldung enthält den tatsächlichen Inhalt.

• Gezielte Bearbeitung (eine Zelle, Formel) – expected_current_values übergeben.

• Massenoperation (tausend Zeilen) – nicht übergeben, sonst verdoppeln Sie die Anfragen und stoßen an das Kontingent.

include_previous_values: true gibt die alten Werte für Prüfzwecke zurück. Wenn expected_current_values gesetzt ist, werden die alten Werte immer geliefert.

Rollback

Bearbeitungen an Docs und Sheets sind im Versionsverlauf von Google Workspace sichtbar. Ein Rollback ist dort möglich.

Kein Tool löscht eine Datei vollständig vom Drive. Destruktive Operationen gibt es nur innerhalb eines Docs und innerhalb einer Tabelle. Eine Datei löschen können Sie nur über die Drive-UI.

Konfiguration

Die Pfade zu den Schlüsseln können über Umgebungsvariablen überschrieben werden:

Update

Führen Sie nach git pull das Upgrade aus. Es baut das Projekt neu auf und fordert Sie, falls im setup-manifest.json neue APIs oder Scopes hinzugekommen sind, erneut zur Authentifizierung auf:

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

Wenn sich das Manifest nicht geändert hat, baut das Skript nur neu und teilt Ihnen mit, dass Sie auf dem neuesten Stand sind. Cursor übernimmt dist/ nach dem MCP-Reload. Der Server muss nicht neu registriert werden.

Zu den Scopes: Der Server verlangt den vollständigen drive-Scope und nicht den eingeschränkten drive.file. Das ist umfassender als die Mindestempfehlung von Google, aber andernfalls wäre es nicht möglich, beliebige verfügbare Dateien zu lesen und in bereits vorhandene Docs zu schreiben (rename, duplicate, Bearbeitungen). Der Scope documents wird für strukturiertes Lesen und batchUpdate benötigt.

Bei einer External-App im Status Testing lebt der Refresh-Token 7 Tage. Danach folgt invalid_grant und erneut npm run auth. Details und Optionen (Internal / Publish) finden Sie in docs/INSTALL.ru.md.

Einschränkungen

• gdrive_create_sheet legt die Tabelle im Drive-Stammverzeichnis ab. Ein Ordner kann nicht ausgewählt werden.

• gdrive_read_file gibt für Sheets nur CSV vom ersten Tab zurück. Weitere Tabs – über gdrive_get_spreadsheet_info.

• gdrive_read_file liefert für Docs immer Markdown. Tabs, Absatzgrenzen, Listen, Anker – gdrive_get_document_info.

• Bevor Sie Format und Struktur eines Docs ändern, lesen Sie zuerst gdrive_get_document_info include_content=true.

• gdrive_replace_all_doc_text betrifft standardmäßig den ersten Tab. Über alle Tabs – nur mit explizitem all_tabs: true.

Entwicklung

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 erstellt ein temporäres Doc, fügt Text über denselben Stream wie MCP ein, prüft über gdrive_get_document_info und legt die Datei am Ende in den Papierkorb.

Lizenz

MIT