mcp-google-sheets

🤔 Was ist das?

mcp-google-sheets ist ein Python-basierter MCP-Server, der als Brücke zwischen jedem MCP-kompatiblen Client (wie Claude Desktop) und der Google Sheets API fungiert. Er ermöglicht Ihnen die Interaktion mit Ihren Google Spreadsheets mithilfe eines definierten Toolset und ermöglicht so leistungsstarke, KI-gesteuerte Automatisierungs- und Datenmanipulations-Workflows.

🚀 Schnellstart (mit uvx )

Im Wesentlichen läuft der Server in einer Zeile: uvx mcp-google-sheets .

Dieser Befehl lädt bei Bedarf automatisch den neuesten Code herunter und führt ihn aus. Die Einrichtung der Google Cloud erfordert jedoch einige Schritte. Bitte lesen Sie die folgenden Schritte.

1. ☁️ Voraussetzung: Google Cloud Setup

   • Sie müssen zunächst die Anmeldeinformationen für die Google Cloud Platform konfigurieren und die erforderlichen APIs aktivieren. Wir empfehlen dringend die Verwendung eines Servicekontos .

   • ➡️ Springen Sie unten zur ausführlichen Einrichtungsanleitung für die Google Cloud Platform .

2. 🐍

   • uvx ist Teil von uv , einem schnellen Python-Paketinstallations- und -resolver. Installieren Sie es, falls noch nicht geschehen:

     # macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Or using pip: # pip install uv

     Befolgen Sie die Anweisungen in der Installationsausgabe, um bei Bedarf

3. 🔑 Wichtige Umgebungsvariablen festlegen (Dienstkonto empfohlen)

   • Sie müssen dem Server mitteilen, wie er sich authentifizieren soll. Legen Sie diese Variablen in Ihrem Terminal fest:

   • (Linux/macOS)

     # Replace with YOUR actual path and folder ID from the Google Setup step export SERVICE_ACCOUNT_PATH="/path/to/your/service-account-key.json" export DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"

   • (Windows CMD)

     set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json" set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"

   • (Windows PowerShell)

     $env:SERVICE_ACCOUNT_PATH = "C:\path\to\your\service-account-key.json" $env:DRIVE_FOLDER_ID = "YOUR_DRIVE_FOLDER_ID"

   • ➡️ Weitere Optionen (OAuth, CREDENTIALS_CONFIG ) finden Sie unter „Detaillierte Authentifizierung und Umgebungsvariablen“ .

4. 🏃 Führen Sie den Server aus!

   • uvx lädt automatisch die neueste Version von mcp-google-sheets herunter und führt sie aus:

     uvx mcp-google-sheets

   • Der Server wird gestartet und druckt Protokolle, die seine Bereitschaft anzeigen.

5. 🔌 Verbinden Sie Ihren MCP-Client

   • Konfigurieren Sie Ihren Client (z. B. Claude Desktop) so, dass er eine Verbindung zum laufenden Server herstellt.

   • Abhängig vom verwendeten Client benötigen Sie Schritt 4 möglicherweise nicht, da der Client den Server für Sie starten kann. Es empfiehlt sich jedoch, Schritt 4 trotzdem zu testen, um sicherzustellen, dass alles richtig eingerichtet ist.

   • ➡️ Beispiele finden Sie unter „Verwendung mit Claude Desktop“ .

Sie sind bereit! Beginnen Sie mit der Befehlsausgabe über Ihren MCP-Client.

✨ Hauptmerkmale

• Nahtlose Integration: Stellt eine direkte Verbindung zu den APIs von Google Drive und Google Sheets her.

• Umfassende Tools: Bietet eine breite Palette an Operationen (CRUD, Auflisten, Batching, Teilen, Formatieren usw.).

• Flexible Authentifizierung: Unterstützt Dienstkonten (empfohlen) , OAuth 2.0 und direkte Anmeldeinformationseinfügung über Umgebungsvariablen.

• Einfache Bereitstellung: Sofortige Ausführung mit uvx (Zero-Install-Gefühl) oder Klonen für die Entwicklung mit uv .

• KI-fähig: Entwickelt für die Verwendung mit MCP-kompatiblen Clients, ermöglicht die Interaktion mit Tabellenkalkulationen in natürlicher Sprache.

🛠️ Verfügbare Tools und Ressourcen

Dieser Server stellt die folgenden Tools zur Interaktion mit Google Sheets bereit:

(Eingabeparameter sind normalerweise Zeichenfolgen, sofern nicht anders angegeben)

• list_spreadsheets : Listet Tabellenkalkulationen im konfigurierten Drive-Ordner (Dienstkonto) auf oder ist für den Benutzer zugänglich (OAuth).

  • Gibt zurück: Liste der Objekte [{id: string, title: string}]

• create_spreadsheet : Erstellt eine neue Tabelle.

  • title (Zeichenfolge): Der gewünschte Titel.

  • Gibt zurück: Objekt mit Tabellenkalkulationsinformationen, einschließlich spreadsheetId .

• get_sheet_data : Liest Daten aus einem Bereich in einem Blatt.

  • spreadsheet_id (Zeichenfolge)

  • sheet (Zeichenfolge): Name des Blatts.

  • range (optionale Zeichenfolge): A1-Notation (z. B. 'A1:C10' , 'Sheet1!B2:D' ). Wenn dieser Wert weggelassen wird, wird das gesamte Blatt gelesen.

  • Gibt zurück: 2D-Array von Zellenwerten.

• get_sheet_formulas : Liest Formeln aus einem Bereich in einem Blatt.

  • spreadsheet_id (Zeichenfolge)

  • sheet (Zeichenfolge): Name des Blatts.

  • range (optionale Zeichenfolge): A1-Notation (z. B. 'A1:C10' , 'Sheet1!B2:D' ). Wenn dieser Wert weggelassen wird, wird das gesamte Blatt gelesen.

  • Gibt zurück: 2D-Array von Zellformeln.

• update_cells : Schreibt Daten in einen bestimmten Bereich. Überschreibt vorhandene Daten.

  • spreadsheet_id (Zeichenfolge)

  • sheet (Zeichenfolge)

  • range (Zeichenfolge): A1-Notation.

  • data (2D-Array): Zu schreibende Werte.

  • Rückgabe: Aktualisiertes Ergebnisobjekt.

• batch_update_cells : Aktualisiert mehrere Bereiche in einem API-Aufruf.

  • spreadsheet_id (Zeichenfolge)

  • sheet (Zeichenfolge)

  • ranges (Objekt): Wörterbuch, das Bereichszeichenfolgen (A1-Notation) 2D-Werte-Arrays zuordnet { "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] } .

  • Gibt zurück: Batch-Update-Ergebnisobjekt.

• add_rows : Fügt Zeilen am Ende eines Blattes an (nach der letzten Zeile mit Daten).

  • spreadsheet_id (Zeichenfolge)

  • sheet (Zeichenfolge)

  • data (2D-Array): Anzuhängende Zeilen.

  • Rückgabe: Aktualisiertes Ergebnisobjekt.

• list_sheets : Listet alle Blattnamen innerhalb einer Tabelle auf.

  • spreadsheet_id (Zeichenfolge)

  • Gibt zurück: Liste der Blattnamen-Strings ["Sheet1", "Sheet2"] .

• create_sheet : Fügt einer Tabelle ein neues Blatt (Registerkarte) hinzu.

  • spreadsheet_id (Zeichenfolge)

  • title (Zeichenfolge): Name für das neue Blatt.

  • Gibt zurück: Neues Blatteigenschaftenobjekt.

• get_multiple_sheet_data : Ruft in einem Aufruf Daten aus mehreren Bereichen aus möglicherweise unterschiedlichen Tabellen ab.

  • queries (Array von Objekten): Jedes Objekt benötigt spreadsheet_id , sheet und range . [{spreadsheet_id: 'abc', sheet: 'Sheet1', range: 'A1:B2'}, ...] .

  • Gibt zurück: Liste von Objekten, die jeweils die Abfrageparameter und abgerufenen data oder einen error enthalten.

• get_multiple_spreadsheet_summary : Ruft Titel, Blattnamen, Kopfzeilen und die ersten Zeilen für mehrere Tabellen ab.

  • spreadsheet_ids (Array von Zeichenfolgen)

  • rows_to_fetch (optionale Ganzzahl, Standard 5): Wie viele Zeilen (einschließlich Kopfzeile) sollen in der Vorschau angezeigt werden.

  • Gibt zurück: Liste der Zusammenfassungsobjekte für jede Tabelle.

• share_spreadsheet : Gibt eine Tabelle mit angegebenen Benutzern/E-Mails und Rollen frei.

  • spreadsheet_id (Zeichenfolge)

  • recipients (Array von Objekten): [{email_address: 'user@example.com', role: 'writer'}, ...] . Rollen: reader , commenter , writer .

  • send_notification (optionaler Boolescher Wert, Standardwert True): E-Mail-Benachrichtigungen senden.

  • Gibt zurück: Wörterbuch mit successes und failures .

• add_columns : Fügt einem Blatt Spalten hinzu. (Parameter überprüfen, falls implementiert)

• copy_sheet : Dupliziert ein Tabellenblatt innerhalb einer Tabelle. (Parameter überprüfen, falls implementiert)

• rename_sheet : Benennt ein vorhandenes Blatt um. (Parameter überprüfen, falls implementiert)

MCP-Ressourcen:

• spreadsheet://{spreadsheet_id}/info : Erhalten Sie grundlegende Metadaten zu einer Google-Tabelle.

  • Gibt zurück: JSON-Zeichenfolge mit Tabellenkalkulationsinformationen.

☁️ Einrichtung der Google Cloud Platform (detailliert)

Diese Einrichtung ist vor dem Ausführen des Servers erforderlich .

1. Erstellen/Auswählen eines GCP-Projekts: Gehen Sie zur Google Cloud Console .

2. APIs aktivieren: Navigieren Sie zu „APIs & Dienste“ -> „Bibliothek“. Suchen und aktivieren Sie:

   • Google Sheets API

   • Google Drive API

3. Anmeldeinformationen konfigurieren: Sie müssen unten eine Authentifizierungsmethode auswählen (Dienstkonto wird empfohlen).

🔑 Authentifizierung und Umgebungsvariablen (detailliert)

Der Server benötigt Anmeldeinformationen für den Zugriff auf Google APIs. Wählen Sie eine Methode:

Methode A: Dienstkonto (empfohlen für Server/Automatisierung) ✅

• Warum? Headless (kein Browser erforderlich), sicher, ideal für Serverumgebungen. Läuft nicht so schnell ab.

• Schritte:

  1. Dienstkonto erstellen: In der GCP-Konsole -> „IAM & Admin“ -> „Dienstkonten“.

     • Klicken Sie auf „+ SERVICEKONTO ERSTELLEN“. Geben Sie ihm einen Namen (z. B. mcp-sheets-service ).

     • Rollen gewähren: Fügen Sie die Rolle Editor für umfassenden Zugriff oder detailliertere Rollen (wie roles/drive.file und bestimmte Sheets-Rollen) für strengere Berechtigungen hinzu.

     • Klicken Sie auf „Fertig“. Suchen Sie das Konto und klicken Sie auf „Aktionen“ (⋮) -> „Schlüssel verwalten“.

     • Klicken Sie auf „SCHLÜSSEL HINZUFÜGEN“ -> „Neuen Schlüssel erstellen“ -> JSON -> „ERSTELLEN“.

     • Laden Sie die JSON-Schlüsseldatei herunter und speichern Sie sie sicher .

  2. Google Drive-Ordner erstellen und freigeben:

     • Erstellen Sie in Google Drive einen Ordner (z. B. „AI Managed Sheets“).

     • Notieren Sie die Ordner-ID aus der URL: https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID .

     • Klicken Sie mit der rechten Maustaste auf den Ordner -> „Freigeben“ -> „Teilen“.

     • Geben Sie die E-Mail-Adresse des Dienstkontos ein (aus der JSON-Datei client_email ).

     • Gewähren Sie dem Editor Zugriff. Deaktivieren Sie „Personen benachrichtigen“. Klicken Sie auf „Teilen“.

  3. Umgebungsvariablen festlegen:

     • SERVICE_ACCOUNT_PATH : Vollständiger Pfad zur heruntergeladenen JSON-Schlüsseldatei.

     • DRIVE_FOLDER_ID : Die ID des freigegebenen Google Drive-Ordners. (Betriebssystemspezifische Beispiele finden Sie

Methode B: OAuth 2.0 (Interaktiv / Persönliche Nutzung) 🧑‍💻

• Warum? Für den persönlichen Gebrauch oder die lokale Entwicklung, bei der eine interaktive Browser-Anmeldung in Ordnung ist.

• Schritte:

  1. OAuth-Zustimmungsbildschirm konfigurieren: In der GCP-Konsole -> „APIs & Dienste“ -> „OAuth-Zustimmungsbildschirm“. Wählen Sie „Extern“, geben Sie die erforderlichen Informationen ein, fügen Sie Bereiche hinzu ( .../auth/spreadsheets , .../auth/drive ) und fügen Sie bei Bedarf Testbenutzer hinzu.

  2. OAuth-Client-ID erstellen: In der GCP-Konsole -> „APIs & Dienste“ -> „Anmeldeinformationen“. „+ ANMELDEINFORMATIONEN ERSTELLEN“ -> „OAuth-Client-ID“ -> Typ: Desktop-App . Benennen Sie sie. „ERSTELLEN“. JSON herunterladen .

  3. Umgebungsvariablen festlegen:

     • CREDENTIALS_PATH : Pfad zur heruntergeladenen JSON-Datei mit den OAuth-Anmeldeinformationen (Standard: credentials.json ).

     • TOKEN_PATH : Pfad zum Speichern des Aktualisierungstokens des Benutzers nach der ersten Anmeldung (Standard: token.json ). Muss beschreibbar sein.

Methode C: Direkte Anmeldeinformationseinfügung (Erweitert) 🔒

• Warum? Nützlich in Umgebungen wie Docker, Kubernetes oder CI/CD, in denen die Dateiverwaltung schwierig, Umgebungsvariablen jedoch einfach und sicher sind. Vermeidet den Dateisystemzugriff.

• Wie? Anstatt einen Pfad zur Anmeldeinformationsdatei anzugeben, geben Sie den Inhalt der Datei, codiert in Base64, direkt in einer Umgebungsvariablen an.

• Schritte:

  1. Holen Sie sich die JSON-Datei mit Ihren Anmeldeinformationen (entweder den Dienstkontoschlüssel oder die OAuth-Client-ID-Datei). Nennen wir sie your_credentials.json .

  2. Generieren Sie die Base64-Zeichenfolge:

     • (Linux/macOS): base64 -w 0 your_credentials.json

     • (Windows PowerShell):

       $filePath = "C:\path\to\your_credentials.json"; # Use actual path $bytes = [System.IO.File]::ReadAllBytes($filePath); $base64 = [System.Convert]::ToBase64String($bytes); $base64 # Copy this output

     • (Achtung): Vermeiden Sie das Einfügen vertraulicher Anmeldeinformationen in nicht vertrauenswürdige Online-Encoder.

  3. Legen Sie die Umgebungsvariable fest:

     • CREDENTIALS_CONFIG : Setzen Sie diese Variable auf die vollständige Base64-Zeichenfolge, die Sie gerade generiert haben.

       # Example (Linux/macOS) - Use the actual string generated export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."

Authentifizierungspriorität und -zusammenfassung

Der Server prüft die Anmeldeinformationen in dieser Reihenfolge:

1. CREDENTIALS_CONFIG (Base64-Inhalt)

2. SERVICE_ACCOUNT_PATH (Pfad zum Dienstkonto JSON)

3. CREDENTIALS_PATH (Pfad zu OAuth JSON) – löst interaktiven Fluss aus, wenn das Token fehlt/abgelaufen ist.

Zusammenfassung der Umgebungsvariablen:

⚙️ Ausführen des Servers (detailliert)

Methode 1: Verwenden von uvx (für Benutzer empfohlen)

Wie im Ultra Quick Start gezeigt, ist dies der einfachste Weg. Legen Sie Umgebungsvariablen fest und führen Sie dann Folgendes aus:

uvx übernimmt vorübergehend das Abrufen und Ausführen des Pakets.

Methode 2: Für die Entwicklung (Klonen des Repo)

Wenn Sie den Code ändern möchten:

1. Klonen: git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets (Tatsächliche URL verwenden)

2. Umgebungsvariablen festlegen: Wie oben beschrieben.

3. Ausführen mit (Verwendet den lokalen Code)

   uv run mcp-google-sheets # Or via the script name if defined in pyproject.toml, e.g.: # uv run start

🔌 Verwendung mit Claude Desktop

Fügen Sie die Serverkonfiguration zu claude_desktop_config.json unter mcpServers hinzu. Wählen Sie den Block aus, der Ihrem Setup entspricht:

(Bei der ersten Verwendung wird möglicherweise ein Browser zur Anmeldung bei Google geöffnet.)

💬 Beispielaufforderungen für Claude

Versuchen Sie nach der Verbindung Eingabeaufforderungen wie:

• „Liste alle Tabellen auf, auf die ich Zugriff habe.“ (oder „in meinem Ordner „AI Managed Sheets“)

• „Erstellen Sie eine neue Tabelle mit dem Titel ‚Vierteljährlicher Verkaufsbericht Q3 2024‘.“

• „Holen Sie sich in der Tabelle ‚Quartalsumsatzbericht‘ die Daten aus Tabelle 1, Bereich A1 bis E10.“

• „Fügen Sie der Tabelle mit der ID 1aBcDeFgHiJkLmNoPqRsTuVwXyZ ein neues Blatt mit dem Namen ‚Zusammenfassung‘ hinzu.“

• „Aktualisieren Sie in meiner Tabelle ‚Projektaufgaben‘, Blatt ‚Aufgaben‘, Zelle B2 auf ‚In Bearbeitung‘.“

• „Fügen Sie diese Zeilen dem Blatt ‚Protokoll‘ in der Tabelle XYZ hinzu: [['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']] “

• „Erhalten Sie eine Zusammenfassung der Tabellenblätter ‚Verkaufsdaten‘ und ‚Bestandszählung‘.“

• „Teilen Sie die Tabelle ‚Team-Urlaubsplan‘ mit team@example.com als Leser und manager@example.com als Autor. Senden Sie keine Benachrichtigungen.“

🤝 Beitragen

Beiträge sind willkommen! Bitte eröffnen Sie ein Issue, um Fehler oder Funktionswünsche zu besprechen. Pull Requests sind willkommen.

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – Einzelheiten finden Sie in der Datei LICENSE .

🙏 Credits

• Erstellt mit FastMCP .

• Inspiriert von kazz187/mcp-google-spreadsheet .

• Verwendet Python-Clientbibliotheken der Google API.