gdocs — Google-Docs-Review-Schleife für Claude Code

Ein MCP-Server, der Claude Code ermöglicht, ein Google Doc und dessen Kommentarthreads zu lesen und dann Korrekturen in dasselbe Doc unter derselben URL zurückzuschreiben.

Entwickelt für den Workflow, in dem Markdown im Repo die Quelle der Wahrheit ist und Google Docs nur die Review-Oberfläche darstellt. Er erspart den Kopier-und-Einfüge-Umweg: kein Einfügen des Entwurfs in Docs, kein Zurückkopieren des Review-Kommentare ins Terminal.

Der Server ist auf Benutzerebene installiert und funktioniert daher in jedem Projekt.

Voraussetzungen

• Node 18+

• Die claude-CLI

• Ein Google-Konto und etwa 10 Minuten in der Google Cloud Console

Installation

git clone https://github.com/uma-victor1/gdocs-mcp.git
cd gdocs-mcp
./install.sh

Das installiert die Abhängigkeiten, überprüft, ob der Server startet, und registriert ihn bei Claude Code auf Benutzerebene. Die beiden folgenden Schritte für die Zugangsdaten erledigst du danach selbst.

1. Google Cloud, einmalig

1. Erstelle ein Projekt: https://console.cloud.google.com/projectcreate

2. Aktiviere Google Docs API und Google Drive API (APIs & Services > Library)

3. OAuth-Zustimmungsbildschirm: Der Benutzertyp External ist für ein persönliches Konto in Ordnung. Füge unter Zielgruppe deine eigene Adresse als Testnutzer hinzu – diesen Schritt zu überspringen ist der häufigste Grund, warum die Zustimmung fehlschlägt.

4. Anmeldedaten > Anmeldedaten erstellen > OAuth-Client-ID > Desktop-App > JSON-Datei herunterladen

5. Speichere die Datei als ~/.config/gdocs-mcp/credentials.json

Die Zugangsdaten liegen absichtlich außerhalb jedes Repos, damit git add -A sie niemals committen kann.

2. Autorisieren, einmal

npm run auth

Google warnt, dass die App unverifiziert ist. Das ist bei einer App mit einem einzigen Nutzer zu erwarten: Erweitert > Weiter zu ... (unsicher). Das Refresh-Token landet in ~/.config/gdocs-mcp/token.json, Modus 0600.

Starte Claude Code neu und bestätige danach mit claude mcp list.

Die 7-Tage-Neuautorisierung und warum

Solange sich der Zustimmungsbildschirm im Modus Testing befindet, lässt Google das Refresh-Token alle 7 Tage ablaufen. Das ist dokumentiertes Verhalten für externe Apps im Testmodus, kein Bug, und es gibt daran kein Weg vorbei für diesen Satz von Scopes: auth/drive ist ein eingeschränkter Scope, und die Veröffentlichung eines eingeschränkten Scopes in die Produktion erfordert eine CASA-Sicherheitsprüfung – das ist für ein Ein-Personen-Tool nicht sinnvoll.

So schlägt etwa einmal pro Woche ein Tool-Aufruf mit „Authorisation expired“ fehl. Beheben:

npm run auth

Fünfzehn Sekunden. Wenn du ein Google Workspace-Konto hast, kannst du das vollständig vermeiden: Erstelle das Cloud-Projekt unter dieser Organisation und stelle den Benutzertyp des Zustimmungsbildschirms auf Intern um. Interne Apps haben keine 7-Tage-Ablauf und keine Liste von Testnutzern.

Tools

Alle Tools akzeptieren eine Doc-URL oder eine rohe fileId.

Der Kommentar-Anker-Kompromiss

Google verankert jeden Kommentar an einer Textstelle. Wird diese Stelle umgeschrieben, löst sich der Thread oder wird automatisch aufgelöst. Also:

• Kleine Korrekturen → replace_text. Anker überleben; Reviewer behalten ihren Kontext.

• Strukturelle Umschreibungen → push_markdown. Schneller, aber Threadverlust luft. Sie liefert die Zahl der vorher offenen Threads, damit der Schaden sichtbar ist statt still unbemerkt bleibt.

• Hinzufügen statt umschreiben → append_text. Es wird nur am Ende eingefügt, damit kein Text verschoben wird kein Anker bricht.

• Antwort bevor du überschreibst. reply_comment sieht der Nachweis, was geändert wurde und warum.

Warum dieses und nicht ein Standard-Server

Ein MCP-Server, der ein OAuth-Token für Docs enthält, kann jedes Dokument im Konto lesen und neu schreiben. Es gibt kein First-Party-Google- oder Anthropic-Docs-MCP; jede veröffentlichte Lösung ist ein Drittanbieter-Paket von einem einzelnen Publisher. Das sind ~250 Zeilen auf Basis des Anthropic MCP SDK und der Google-Client-Bibliothek – klein genug, um es zu lesen, bevor man ihm vertraut.

Nur-Lese-Modus

claude mcp remove gdocs -s user
claude mcp add gdocs -s user -e GDOCS_MCP_READONLY=1 -- node "$PWD/server.mjs"

Lesen funktioniert weiterhin; jedes Schreib-Tool verweigert die. Nützlich, wenn jemand anderes die Eigentümer eines Docs ist.

Fehlerbehandlung

Du kannst den Server jederzeit unabhängig mit npm run smoke überprüfen.

Um ein einzelnes Tool ohne Claude Code zu benutzen:

node call.mjs read_comments '{"doc":"https://docs.google.com/document/d/FILEID/edit"}'

Zugriff widerrufen

Öffne https://myaccount.google.com/permissions und lösche danach ~/.config/gdocs-mcp/token.json.

Aufbau

server.mjs         the nine tools
google.mjs         auth + Drive/Docs clients; credential paths
auth.mjs           one-time interactive OAuth   (npm run auth)
smoke.mjs          starts the server, lists tools  (npm run smoke)
call.mjs           invoke one tool from the shell, for debugging
install.sh         deps, verify, register at user scope
docs/guide.html    the setup walkthrough as a standalone page

Lizenz

MIT. Siehe LICENSE.