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. 🐍 uv installieren
   • 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 uv zu Ihrem PATH hinzuzufügen.
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 im Ultra Quick Start .)

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 uv : (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.