gdrive-write-mcp

Ein MCP-Server, der KI-Assistenten echten Schreibzugriff auf Google Drive gibt — In-Place-Inhaltsaktualisierungen, Anhänge sowie Suchen-und-Ersetzen-Bearbeitungen, die die Datei-ID, Freigabeeinstellungen, Kommentare und den Revisionsverlauf bewahren.

Das Problem

Die meisten Google-Drive-Integrationen für KI-Assistenten sind auf Lesen plus Erstellen ausgelegt. Sie können Dateien durchsuchen, lesen, neue anlegen und alte in den Papierkorb verschieben – aber sie haben keine Möglichkeit, den Inhalt einer bereits vorhandenen Datei zu ändern.

Das klingt nach einer kleinen Lücke. Ist es aber nicht. Ohne In-Place-Schreibvorgänge wird aus „Dieses Dokument bearbeiten“:

1. Die Datei lesen.

2. Eine neue Datei mit dem korrigierten Inhalt erstellen.

3. Die alte in den Papierkorb verschieben.

Das Ergebnis enthält technisch gesehen den richtigen Text, und alles andere daran ist falsch:

gdrive-write-mcp schließt diese Lücke. Die Google-Drive-API hat In-Place-Inhaltsaktualisierungen schon immer unterstützt; dies ist ein kleiner, fokussierter Server, der sie über MCP bereitstellt.

Related MCP server: Google Docs MCP Server

Was es tut

Bearbeiten

• replace_in_file — exaktes Suchen-und-Ersetzen. Das Standardwerkzeug: Es verlangt nicht, das ganze Dokument erneut zu senden, und kann nicht versehentlich Inhalte verwerfen, die nie erwähnt wurden.

• append_to_file / prepend_to_file — fügt an das eine oder andere Ende an, ohne das bereits Vorhandene erneut zu senden. Entwickelt für Logs, Journale und Changelogs.

• update_file_content — ersetzt das gesamte Dokument. Von Natur aus destruktiv, deshalb ist es für das Modell als letzte Möglichkeit dokumentiert, nicht als Standard.

Lesen

• read_file — Inhalt plus das revisionToken, mit dem der nächste Schreibvorgang abgesichert wird.

• get_file_metadata — prüfen, ob sich eine Datei verändert hat, ohne sie herunterzuladen.

• search_files — Drive-Abfragesyntax, damit ein Dateiname in die ID umgewandelt werden kann, die die Schreibwerkzeuge benötigen.

• list_revisions — der Verlauf, den In-Place-Bearbeitung bewahrt.

Erstellen

• create_file — für wirklich neue Dokumente, mit optionaler Konvertierung in ein natives Google Doc oder Sheet.

Zwei Dinge, die es richtig macht

1. Gleichzeitige Bearbeitungen werden abgelehnt, nicht stillschweigend verschluckt

Der Fehlermodus eines naiven Schreibwerkzeugs ist leise und teuer: Man liest ein Dokument, denkt dreißig Sekunden nach und schreibt es zurück – und überschreibt dabei den Absatz, den ein Kollege in der Zwischenzeit hinzugefügt hat. Niemand erhält eine Fehlermeldung. Niemand bemerkt es, bis der Absatz Tage später fehlt.

Jedes Lesen hier gibt ein revisionToken zurück, und jeder Schreibvorgang akzeptiert eines:

read_file(fileId)                    → revisionToken: "0B1a2…"
update_file_content(fileId, content, expectedRevisionToken: "0B1a2…")

Wenn sich die Datei geändert hat, wird der Schreibvorgang mit einem Fehler abgelehnt, der dem Modell genau sagt, was zu tun ist — erneut lesen, erneut anwenden, erneut schreiben —, statt nur ein bloßes 409 zu liefern. Die gezielten Werkzeuge (replace_in_file, append_to_file, prepend_to_file) lesen und schreiben in einem einzigen Aufruf, sodass sie den Schutz automatisch mit sich führen und man selbst nie ein Token in die Hand nehmen muss.

Drive legt headRevisionId nur für Dateien mit echtem Binärinhalt offen — native Google-Docs und -Sheets haben keins, und genau dort ist gleichzeitiges menschliches Bearbeiten am wahrscheinlichsten, denn das sind die Dateien, die jemand in einem Browser-Tab geöffnet hat. Für diese fällt das Token auf modifiedTime zurück, sodass auch native Dateien geschützt sind.

2. Native Google-Dateien werden ehrlich behandelt

Drive speichert zwei sehr verschiedene Arten von Dingen, und ihre Vermischung ist die häufigste Fehlerquelle in Drive-Integrationen:

• Hochgeladene Dateien (text/markdown, application/pdf, …) — Bytes rein, Bytes raus.

• Native Editor-Dateien (application/vnd.google-apps.document, …) — haben keine eigenen Bytes. Sie werden gelesen, indem man sie in ein konkretes Format exportiert; geschrieben werden sie, indem man ein Format hochlädt, das Drive beim Import zurückwandelt.

Dieser Server erkennt, was was ist, und leitet entsprechend weiter. Docs werden in Markdown statt in reinen Text exportiert, gerade damit ein Lese-Ändern-Schreibe-Durchlauf Überschriften, Listen und Hervorhebungen bewahrt, statt das Dokument stillschweigend einzuebnen. Binärdateien werden base64-kodiert und nicht als UTF-8 dekodiert, sodass ein PDF beim Durchlauf durch ein Textwerkzeug nie beschädigt werden kann.

Installation

git clone https://github.com/anaborne/gdrive-write-mcp.git
cd gdrive-write-mcp
npm install
npm run build

Erfordert Node 18 oder neuer.

Einrichtung

Schritt 1 — Google-OAuth-Client erstellen

1. Öffnen Sie die Google Cloud Console und erstellen Sie ein Projekt (oder wählen Sie ein vorhandenes aus).

2. Aktivieren Sie die Google Drive API: APIs & Dienste → Bibliothek → Google Drive API → Aktivieren.

3. Konfigurieren Sie den OAuth-Zustimmungsbildschirm: APIs & Dienste → OAuth-Zustimmungsbildschirm. Wählen Sie Extern, füllen Sie die erforderlichen Felder aus und fügen Sie unter Testnutzer Ihr eigenes Google-Konto hinzu. (Solange sich die App im Modus „Testing“ befindet, können nur aufgeführte Testnutzer sie autorisieren – genau das ist für ein persönliches Werkzeug gewünscht.)

4. Erstellen Sie Anmeldedaten: APIs & Dienste → Anmeldedaten → Anmeldedaten erstellen → OAuth-Client-ID → Desktop-App.

5. Kopieren Sie die Client-ID und das Client-Secret.

Schritt 2 — Ein Refresh-Token erhalten

cp .env.example .env
# put GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env
npm run authorize

Dies öffnet einen einmaligen Zustimmungsablauf auf http://localhost:4181 und gibt ein Refresh-Token aus. Fügen Sie es der .env hinzu:

GOOGLE_CLIENT_ID=1234567890-abcdef.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-…
GOOGLE_REFRESH_TOKEN=1//0g…

Schritt 3 — Ihren MCP-Client auf den Server ausrichten

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "gdrive-write": {
      "command": "node",
      "args": ["/absolute/path/to/gdrive-write-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "…",
        "GOOGLE_CLIENT_SECRET": "…",
        "GOOGLE_REFRESH_TOKEN": "…"
      }
    }
  }
}

Claude Code:

claude mcp add gdrive-write \
  --env GOOGLE_CLIENT_ID=… \
  --env GOOGLE_CLIENT_SECRET=… \
  --env GOOGLE_REFRESH_TOKEN=… \
  -- node /absolute/path/to/gdrive-write-mcp/dist/index.js

Alles andere — der Server spricht MCP über stdio. Starten Sie node dist/index.js als Unterprozess mit diesen drei gesetzten Umgebungsvariablen.

Schritt 4 — Verifizieren, dass es funktioniert

npm run verify

Das führt eine echte End-to-End-Prüfung gegen Ihr Drive aus: Es startet den Server auf dieselbe Weise, wie ein MCP-Client es täte, steuert ihn über stdio mit dem offiziellen MCP-Client und verifiziert das Verhalten, das dieses Projekt verspricht — einschließlich, dass ein veralteter Schreibvorgang abgelehnt wird, dass eine abgelehnte Schreiboperation die Datei unangetastet lässt, dass die Datei-ID nach jeder Bearbeitung unverändert bleibt und dass ein natives Google Doc einen Lese-Bearbeiten-Lese-Durchlauf als Doc übersteht.

Es erstellt zwei temporäre Dateien in Ihrem Drive und verschiebt sie in den Papierkorb, wenn es fertig ist, auch wenn es zwischendurch fehlschlägt. Erwarten Sie eine grüne Zusammenfassungszeile:

✓ ALL 41 CHECKS PASSED — the server works against live Drive.

Wenn etwas fehlschlägt, benennt die Ausgabe die konkrete Prüfung und zeigt, was zurückkam. Die Konflikt- und die Native-Doc-Prüfung enthalten zusätzliche Diagnosen, die erklären, was ein bestimmter Fehler bedeutet — ein mit Backslash maskiertes # bedeutet zum Beispiel, dass der Inhalt als reiner Text statt als Markdown importiert wurde.

Das ist keine Formalität. Die Unit-Suite war bei 49 Tests grün, und die CI war erfolgreich, während ein echter Fehler im Code saß: Das Erstellen eines nativen Docs aus Markdown erzeugte stillschweigend ein Doc, das die wörtlichen Zeichen # Heading enthielt. Nur der Live-Lauf hat es bemerkt, weil der Mock dieselbe falsche Annahme kodiert hatte wie die Implementierung. Führen Sie dies nach jeder Änderung an drive.ts oder mime.ts aus.

Tool-Referenz

read_file

Gibt Inhalt plus revisionToken, mimeType und modifiedTime zurück. Native Dateien werden exportiert (Docs → Markdown, Sheets → CSV, Slides → Klartext); Binärdateien kommen base64-kodiert zurück.

replace_in_file

Der Abgleich ist wörtlich, nicht Regex — ein . oder $1 im Suchtext bedeutet exakt diese Zeichen. Wenn oldString mehr als einmal vorkommt und replaceAll false ist, schlägt der Aufruf fehl, statt zu raten, denn eine stille Bearbeitung des falschen Vorkommens ist die Art von Fehler, die niemand bemerkt.

append_to_file / prepend_to_file

Wiederholte Anhänge bleiben gleichmäßig getrennt — keine fortlaufenden Zeilen, keine sich vergrößernden Lücken aus Leerzeilen.

update_file_content

Ersetzt alles. Ohne expectedRevisionToken werden Änderungen überschrieben, die seit dem letzten Lesen der Datei vorgenommen wurden.

create_file

search_files

name contains 'budget'
fullText contains 'quarterly review'
'FOLDER_ID' in parents
mimeType = 'application/vnd.google-apps.document'

get_file_metadata / list_revisions

Beide akzeptieren fileId; list_revisions akzeptiert außerdem ein optionales pageSize.

Sicherheit

Warum der volle Drive-Scope. Dieser Server fordert standardmäßig https://www.googleapis.com/auth/drive an. Der engere drive.file-Scope gewährt nur Zugriff auf Dateien, die die App selbst erstellt hat, was für ein Werkzeug, dessen ganzer Zweck darin besteht, Dokumente zu bearbeiten, die Sie bereits haben, nicht funktionieren kann. Das ist ein echter Kompromiss, klar ausgesprochen statt versteckt: Das Token kann alles im Drive des autorisierten Kontos lesen und schreiben.

Wenn Ihr Arbeitsablauf ausschließlich Dateien betrifft, die der Assistent selbst erstellt, fordern Sie stattdessen den engeren Scope an – sowohl für den Autorisierungsschritt als auch für den Server:

GOOGLE_OAUTH_SCOPE=drive.file

Die beiden müssen übereinstimmen. Ein Refresh-Token trägt den Scope, mit dem es gewährt wurde; wenn Sie also ein Token unter dem einen ausstellen und den Server unter dem anderen betreiben, entstehen bei Aufrufen verwirrende 403s. Der Server gibt beim Start eine Warnung an stderr aus, wenn der Pro-Datei-Scope aktiv ist, sodass ein späteres 404 bei einem fremden Dokument kein Rätsel ist.

Möglichkeiten, das einzugrenzen:

• Autorisieren Sie ein dediziertes Google-Konto und teilen Sie nur die bestimmten Dateien oder Ordner, die erreichbar sein sollen.

• Belassen Sie die OAuth-App im Testing-Modus, sodass nur aufgeführte Testnutzer sie autorisieren können.

• Widerrufen Sie den Zugriff jederzeit unter myaccount.google.com/permissions.

Umgang mit dem Refresh-Token. Es ist ein Passwort für Ihr Drive. Es läuft von selbst nie ab. Bewahren Sie es in .env (hier git-ignoriert) oder in der Konfiguration Ihres MCP-Clients auf, niemals in einer committeten Datei. Wenn es durchsickert, widerrufen Sie es über den obigen Link – das macht es sofort ungültig.

Keine Telemetrie. Dieser Server führt Netzwerkaufrufe ausschließlich an die APIs von Google aus und sonst nirgendwohin.

Fehlerbehebung

Error 403: access_denied

Google lehnt den Zustimmungsbildschirm ab, bevor irgendein Code ausgeführt wird. auth/drive ist ein eingeschränkter Scope – die strengste Stufe von Google – und eingeschränkte Scopes werden blockiert, sofern die App nicht so konfiguriert ist, dass sie sie zulässt. Prüfen Sie in Google Auth Platform in dieser Reihenfolge:

1. Zielgruppe → Veröffentlichungsstatus ist „Testing“, nicht „In production“. Eine unverifizierte App in Produktion kann eingeschränkte Scopes überhaupt nicht nutzen, für niemanden, auch nicht für ihren eigenen Autor. Der Testing-Modus erlaubt sie für bis zu 100 aufgeführte Testnutzer ohne Verifizierung.

2. Zielgruppe → Testnutzer enthält das genaue Konto, mit dem Sie sich anmelden.

3. Branding → App-Name, E-Mail-Adresse für den Nutzersupport und E-Mail-Adresse für den Entwicklerkontakt sind alle gespeichert. Ein unvollständiger Zustimmungsbildschirm ist ein ungültiger.

Änderungen brauchen ein paar Minuten, um wirksam zu werden. Wenn es direkt nach einer Änderung immer noch fehlschlägt, warten Sie fünf Minuten und versuchen Sie es erneut.

Um es vollständig zu umgehen, fordern Sie den nicht eingeschränkten Pro-Datei-Scope an, der nie blockiert wird:

GOOGLE_OAUTH_SCOPE=drive.file npm run authorize

Jede Datei, die npm run verify berührt, wird von ihr selbst erstellt, daher besteht die vollständige Verifikationssuite unter drive.file – nützlich, um zu bestätigen, dass der Server funktioniert, während die Zustimmungskonfiguration noch geklärt wird. Sie erreicht keine anderswo erstellten Dokumente, ist also ein Diagnosepfad und keine dauerhafte Lösung.

Entwicklung

npm install
npm run build       # compile TypeScript to dist/
npm test            # build, then run the unit suite (no network, no credentials)
npm run verify      # end-to-end check against a real Drive account
npm run typecheck   # type-check without emitting
npm run watch       # rebuild on change

npm test und npm run verify beantworten unterschiedliche Fragen. Die Unit-Testsuite mockt die Drive-API: Sie beweist, dass die Logik stimmt, läuft in CI und benötigt keine Anmeldedaten. npm run verify beweist, dass die Integration stimmt – dass Google sich tatsächlich so verhält, wie dieser Server es annimmt, insbesondere bei der Konvertierung nativer Dateien und bei Revisions-Tokens. Eine Änderung an drive.ts oder mime.ts sollte mit beidem geprüft werden.

Der Code ist so organisiert, dass die Teile, die ein Dokument still beschädigen können, ohne Netzwerkzugriff testbar sind:

src/
  index.ts    entry point; stdio transport
  auth.ts     OAuth client from environment
  drive.ts    Drive operations, incl. the concurrency guard
  edits.ts    pure text transforms — no I/O, fully unit-tested
  mime.ts     native vs. binary vs. textual classification
  tools.ts    MCP tool definitions and handlers
  errors.ts   error types written to be actionable by a model

Die Suite deckt die Randfälle von Suchen/Ersetzen ab (regex-ähnliche Literale, $& in Ersetzungen, mehrzeilige Ziele, mehrdeutige Übereinstimmungen), die Nahtstellenlogik für Anhängen/Voranstellen, die MIME-Klassifizierung und den Nebenläufigkeitsschutz – einschließlich der Tatsache, dass ein konkurrierender Schreibvorgang niemals die API erreicht.

Mitwirken

Issues und Pull-Requests sind willkommen. Öffnen Sie für eine Änderung jeder Größe zuerst ein Issue, damit der Ansatz vor der Arbeit abgestimmt werden kann.

Wenn Sie ein Tool hinzufügen, fügen Sie Tests für seine reine Logik hinzu und schreiben Sie seine Beschreibung für das Modell, das sie lesen wird – sagen Sie, wann man es anstelle seiner Nachbarn einsetzen sollte, nicht nur, was es tut.

Lizenz

MIT – siehe LICENSE.