apps-script-mcp-server

Ein MCP-Server, mit dem Claude Google Apps Script-Code (.gs, .html, appsscript.json) direkt in ein Skriptprojekt lesen und pushen kann – kein manuelles Kopieren und Einfügen in den Apps Script-Editor mehr nötig.

Entwickelt für das Kwara-Krankheitsüberwachungssystem (KWARAB-Dashboard), funktioniert aber mit jedem Apps Script-Projekt, auf das Sie Bearbeitungszugriff haben.

Was es kann

Wichtige Einschränkung vorab: Das Pushen von Code mit apps_script_update_file / apps_script_update_content aktualisiert das bearbeitbare Projekt – genauso, als ob Sie im Skript-Editor tippen und speichern. Es aktualisiert nicht automatisch bereits bereitgestellte Instanzen (z. B. eine Live-Web-App-URL oder Trigger, die an eine bestimmte bereitgestellte Version gebunden sind). Um Änderungen live zu schalten, erstellen Sie eine Version (apps_script_create_version) und stellen Sie dann aus dem Apps Script-Editor erneut bereit – dieser Server greift nicht in die Veröffentlichung von Bereitstellungen ein, bewusst, da dies eine folgenreichere Aktion ist, die es wert ist, die ersten Male von Hand durchgeführt zu werden.

1. Einmalige Google Cloud-Einrichtung (zuerst erledigen)

Sie benötigen ein Google Cloud-Projekt mit aktivierter Apps Script-API und einem OAuth-Client. Dies dauert etwa 5 Minuten.

1. Ein Google Cloud-Projekt erstellen oder auswählen Gehen Sie zu https://console.cloud.google.com/projectcreate und erstellen Sie ein Projekt (jeder Name ist in Ordnung – z. B. „kwarab-apps-script-mcp“). Wenn Sie bereits ein GCP-Projekt haben, das Sie für andere Kwara/Ekiti-Arbeiten nutzen, können Sie es wiederverwenden.

2. Apps Script-API für das Projekt aktivieren Gehen Sie zu https://console.cloud.google.com/apis/library/script.googleapis.com, wählen Sie Ihr Projekt aus und klicken Sie auf Aktivieren.

3. OAuth-Zustimmungsbildschirm konfigurieren Gehen Sie zu https://console.cloud.google.com/apis/credentials/consent

   • Benutzertyp: Extern (es sei denn, Sie haben eine Google Workspace-Organisation, dann ist Intern in Ordnung)

   • App-Namen ausfüllen (z. B. „Apps Script MCP“), Ihre E-Mail als Support-Kontakt

   • Bereiche: Sie können hier das Hinzufügen von Bereichen überspringen – der Server fordert sie direkt an

   • Testnutzer: Ihre eigene Google-Konto-E-Mail hinzufügen (erforderlich, solange die App den Status „Testen“ hat, was für den persönlichen/internen Gebrauch in Ordnung ist)

4. Einen OAuth-Client erstellen Gehen Sie zu https://console.cloud.google.com/apis/credentials

   • Klicken Sie auf Anmeldedaten erstellen → OAuth-Client-ID

   • Anwendungstyp: Desktop-App

   • Geben Sie einen beliebigen Namen ein (z. B. „Apps Script MCP Desktop“)

   • Klicken Sie auf Erstellen, dann auf JSON herunterladen

5. Die heruntergeladene Datei als credentials.json im Stammverzeichnis dieses Projekts speichern (gleicher Ordner wie diese README). Diese Datei nicht committen oder teilen – sie identifiziert Ihren OAuth-Client (nicht Ihr persönliches Konto, aber dennoch privat halten).

6. Apps Script-API für Ihr eigenes Google-Konto aktivieren Dies ist getrennt von Schritt 2 (dort wird die API für das Projekt aktiviert; hier wird sie für das Google-Konto aktiviert, das das Skript besitzt/bearbeitet). Gehen Sie zu https://script.google.com/home/usersettings und aktivieren Sie „Google Apps Script API“.

2. Installieren und autorisieren

npm install
npm run build
npm run authorize

npm run authorize öffnet Ihren Browser, fordert Sie auf, sich mit dem Google-Konto anzumelden, das Zugriff auf das Kwara-Krankheitsüberwachungs-Apps-Script-Projekt hat, und bittet Sie um Genehmigung des Zugriffs. Nach der Genehmigung wird ein Aktualisierungstoken in token.json in diesem Ordner gespeichert – Sie müssen dies nur einmal tun (führen Sie es erneut aus, wenn Sie den Zugriff jemals widerrufen oder das Google-Konto wechseln).

Wenn sich nichts automatisch öffnet: Das Terminal gibt eine URL aus – kopieren Sie diese in einen beliebigen Browser, genehmigen Sie, und Sie werden zurück zu localhost weitergeleitet, wo das Skript lauscht; das Terminal bestätigt den Erfolg.

3. Mit Claude verbinden

Option A: Lokal (stdio) – Claude Code / Claude Desktop

Zu Ihrer MCP-Konfiguration hinzufügen (z. B. claude_desktop_config.json oder Ihre Claude Code MCP-Einstellungen):

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

Starten Sie Claude Desktop / Claude Code nach dem Hinzufügen neu. Sie sollten apps-script in der Liste der verbundenen MCP-Server sehen, mit verfügbaren Tools wie apps_script_update_file.

Option B: Remote (HTTP), z. B. gehostet auf Render

Der Server läuft auch als eigenständiger HTTP-Dienst – setzen Sie TRANSPORT=http. Dies wird durch render.yaml in diesem Repository automatisch konfiguriert. Siehe Bereitstellung auf Render unten.

Ein entfernter Server ist für jeden erreichbar, der seine URL kennt. Daher muss jede Anfrage an /mcp ein Bearer-Token enthalten, das der von Ihnen gesetzten Umgebungsvariablen MCP_SERVER_TOKEN entspricht:

Authorization: Bearer <your MCP_SERVER_TOKEN value>

Fügen Sie in den Einstellungen des entfernten MCP-Connectors von Claude die Server-URL (https://<your-service>.onrender.com/mcp) hinzu und setzen Sie diesen Header. /healthz ist absichtlich nicht authentifiziert, damit Render's Health Checks darauf zugreifen können.

Bereitstellung auf Render

Dieses Repository enthält ein render.yaml-Blueprint, sodass Render den Dienst mit den meisten voreingestellten Einstellungen erstellen kann.

1. Im Render-Dashboard: Neu → Blueprint, verbinden Sie Ihr GitHub-Konto, falls noch nicht geschehen, und wählen Sie dieses Repository aus. Render liest render.yaml.

2. Render wird Sie nach den Umgebungsvariablen fragen, die mit sync: false markiert sind:

   • MCP_SERVER_TOKEN – erfinden Sie eine lange zufällige Zeichenfolge (z. B. openssl rand -hex 32). Dies muss Claude als Bearer-Token senden.

   • GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET, GOOGLE_OAUTH_REFRESH_TOKEN – generieren Sie diese zuerst lokal (Schritte 1–2 oben, einschließlich npm run authorize), öffnen Sie dann die resultierende token.json und kopieren Sie client_id, client_secret und refresh_token in die Umgebungsvariablenfelder von Render. Render erhält nie einen Browser, daher ersetzt dieser Headless-Anmeldedatenpfad den lokalen npm run authorize-Schritt.

3. Bereitstellen. Sobald live, ist der MCP-Endpunkt https://<your-service>.onrender.com/mcp.

4. Im kostenlosen Plan fährt Render den Dienst nach Inaktivität herunter – die erste Anfrage nach dem Leerlauf wird langsam sein (Kaltstart), während er wieder hochfährt.

4. Verwendung

Sie benötigen die Skript-ID des Kwara-Krankheitsüberwachungs-Apps-Script-Projekts. Finden Sie sie, indem Sie das Projekt unter https://script.google.com öffnen und die ID aus der URL kopieren:

https://script.google.com/home/projects/<THIS_IS_THE_SCRIPT_ID>/edit

(Wenn das Apps Script an das KWARAB-Google-Sheet gebunden ist und nicht eigenständig ist, öffnen Sie das Sheet → Erweiterungen → Apps Script, um zum selben Editor und derselben URL zu gelangen.)

Dann können Sie in einer Claude-Unterhaltung, die mit diesem MCP-Server verbunden ist, Dinge sagen wie:

• „Zeig mir den aktuellen Code.gs im Skript <scriptId>“

• „Aktualisiere die sendAlertEmail-Funktion in Code.gs, um auch den DSNO-Supervisor in CC zu setzen“

• „Pushe diese neue Utils.gs-Datei mit diesen Hilfsfunktionen: …“

• „Erstelle eine neue Version mit dem Namen ‚AFP EPID Auto-Compose-Logik hinzufügen‘“

Sicherheitshinweise

• credentials.json und token.json gewähren beide Zugriff auf Apps Script-Projekte, die Sie bearbeiten können. Halten Sie sie außerhalb der Versionskontrolle (eine .gitignore ist enthalten) und teilen Sie sie nicht.

• Die angeforderten OAuth-Bereiche (script.projects, script.deployments) umfassen keinen Zugriff auf Gmail, Sheets oder Drive über das hinaus, was zum Lesen/Schreiben von Skriptprojektinhalten und zum Überprüfen von Bereitstellungen erforderlich ist.

• Um den Zugriff jederzeit zu widerrufen: https://myaccount.google.com/permissions → den OAuth-Client-Namen finden, den Sie in Schritt 4 oben festgelegt haben → Zugriff entfernen. Löschen Sie anschließend token.json.

Fehlerbehebung