mcp-google-sheet

🤔 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 über eine definierte Reihe von Tools und unterstützt so leistungsstarke Automatisierungs- und Datenverarbeitungs-Workflows, die von KI gesteuert werden.

Related MCP server: mcp-google-sheets

🚀 Schnellstart (mit uvx)

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

Dieser Befehl lädt automatisch den neuesten Code herunter und führt ihn aus. Wir empfehlen, immer @latest zu verwenden, um sicherzustellen, dass Sie die neueste Version mit den aktuellsten Funktionen und Fehlerbehebungen erhalten.

Weitere Informationen zu den unten verwendeten IDs finden Sie im ID-Referenzhandbuch.

1. ☁️ Voraussetzung: Google Cloud Einrichtung

   • Sie müssen zuerst Google Cloud Platform-Anmeldeinformationen konfigurieren und die erforderlichen APIs aktivieren. Wir empfehlen dringend die Verwendung eines Servicekontos.

   • ➡️ Springen Sie zur Detaillierten Google Cloud Platform Einrichtung weiter unten.

2. 🐍 uv installieren

   • uvx ist Teil von uv, einem schnellen Python-Paketinstallierer und -auflöser. Installieren Sie es, falls Sie es noch nicht haben:

     # 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

     Folgen Sie den Anweisungen in der Installationsausgabe, um uv bei Bedarf zu Ihrem PATH hinzuzufügen.

3. 🔑 Wesentliche Umgebungsvariablen festlegen (Servicekonto empfohlen)

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

   • (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 & Umgebungsvariablen.

4. 🏃 Server starten!

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

     uvx mcp-google-sheets@latest

   • Der Server startet und protokolliert Meldungen, die anzeigen, dass er bereit ist.

   • 💡 Profi-Tipp: Verwenden Sie immer @latest, um sicherzustellen, dass Sie die neueste Version mit Fehlerbehebungen und Funktionen erhalten. Ohne @latest verwendet uvx möglicherweise eine gecachte ältere Version.

5. 🔌 MCP-Client verbinden

   • Konfigurieren Sie Ihren Client (z. B. Claude Desktop), um eine Verbindung zum laufenden Server herzustellen.

   • Je nach verwendetem Client benötigen Sie Schritt 4 möglicherweise nicht, da der Client den Server für Sie starten kann. Es ist jedoch eine gute Praxis, Schritt 4 trotzdem zu testen, um sicherzustellen, dass alles richtig eingerichtet ist.

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

6. ⚡ Optional: Tool-Filterung aktivieren (Kontextverbrauch reduzieren)

   • Standardmäßig sind alle 19 Tools aktiviert (~13K Tokens). Um den Kontextverbrauch zu reduzieren, aktivieren Sie nur die Tools, die Sie benötigen.

   • ➡️ Details finden Sie unter Tool-Filterung.

Sie sind bereit! Beginnen Sie, Befehle über Ihren MCP-Client auszugeben.

✨ Hauptfunktionen

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

• Umfassende Tools: Bietet eine breite Palette an Operationen (CRUD, Auflistung, Stapelverarbeitung, Freigabe, Formatierung usw.).

• Flexible Authentifizierung: Unterstützt Servicekonten (empfohlen), OAuth 2.0 und die direkte Injektion von Anmeldeinformationen über Umgebungsvariablen.

• Einfache Bereitstellung: Sofort ausführbar mit uvx (Zero-Install-Gefühl) oder Klonen für die Entwicklung mit uv.

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

• Tool-Filterung: Reduzieren Sie die Nutzung des Kontextfensters, indem Sie nur die benötigten Tools mit --include-tools oder der Umgebungsvariable ENABLED_TOOLS aktivieren.

🎯 Tool-Filterung (Kontextverbrauch reduzieren)

Problem: Standardmäßig stellt dieser MCP-Server alle 19 Tools bereit, was ~13.000 Tokens verbraucht, bevor überhaupt ein Gespräch beginnt. Wenn Sie nur wenige Tools benötigen, verschwendet dies wertvollen Platz im Kontextfenster.

Lösung: Verwenden Sie die Tool-Filterung, um nur die Tools zu aktivieren, die Sie tatsächlich verwenden.

So aktivieren Sie die Tool-Filterung

Sie können Tools auf zwei Arten filtern:

1. Befehlszeilenargument --include-tools:

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": [
           "mcp-google-sheets@latest",
           "--include-tools",
           "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         ],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json"
         }
       }
     }
   }

2. Umgebungsvariable ENABLED_TOOLS:

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": ["mcp-google-sheets@latest"],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json",
           "ENABLED_TOOLS": "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         }
       }
     }
   }

Verfügbare Tool-Namen

Verwenden Sie beim Filtern diese exakten Tool-Namen (durch Kommas getrennt, ohne Leerzeichen):

Häufigste Tools (empfohlene Teilmenge):

• get_sheet_data - Aus Tabellenkalkulationen lesen

• update_cells - In Tabellenkalkulationen schreiben

• list_spreadsheets - Tabellenkalkulationen finden

• list_sheets - Registerkarten navigieren

Alle verfügbaren Tools:

• add_columns

• add_rows

• batch_update

• batch_update_cells

• copy_sheet

• create_sheet

• create_spreadsheet

• find_in_spreadsheet

• get_multiple_sheet_data

• get_multiple_spreadsheet_summary

• get_sheet_data

• get_sheet_formulas

• list_folders

• list_sheets

• list_spreadsheets

• rename_sheet

• search_spreadsheets

• share_spreadsheet

• update_cells

Hinweis: Wenn weder --include-tools noch ENABLED_TOOLS angegeben ist, sind alle Tools aktiviert (Standardverhalten).

🛠️ Verfügbare Tools & Ressourcen

Dieser Server stellt die folgenden Tools für die Interaktion mit Google Sheets bereit:

Weitere Informationen zu den unten verwendeten IDs finden Sie im ID-Referenzhandbuch.

(Eingabeparameter sind normalerweise Zeichenfolgen, sofern nicht anders angegeben)

• list_spreadsheets: Listet Tabellenkalkulationen im konfigurierten Drive-Ordner (Service Account) oder für den Benutzer zugängliche (OAuth) auf.

  • folder_id (optionaler String): Google-Drive-Ordner-ID, in der gesucht werden soll. Aus der URL abrufbar. Wenn nicht angegeben, wird der konfigurierte Standardordner verwendet oder „My Drive“ durchsucht.

  • Rückgabe: Liste von Objekten [{id: string, title: string}]

• create_spreadsheet: Erstellt eine neue Tabellenkalkulation.

  • title (String): Der gewünschte Titel für die Tabellenkalkulation. Beispiel: „Quarterly Report Q4“.

  • folder_id (optionaler String): Google-Drive-Ordner-ID, in der die Tabellenkalkulation erstellt werden soll. Aus der URL abrufbar. Wenn nicht angegeben, wird der konfigurierte Standardordner oder das Root-Verzeichnis verwendet.

  • Rückgabe: Objekt mit Tabellenkalkulationsinformationen, einschließlich spreadsheetId, title und folder.

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

  • spreadsheet_id (String): Die Tabellenkalkulations-ID (aus der URL).

  • sheet (String): Name des Blatts/Tabs (z. B. „Sheet1“).

  • range (optionaler String): A1-Notation (z. B. 'A1:C10', 'Sheet1!B2:D'). Wenn nicht angegeben, wird das gesamte Blatt/Tab gelesen, das durch sheet angegeben ist.

  • include_grid_data (optionaler Boolean, Standard False): Wenn True, werden vollständige Rasterdaten einschließlich Formatierung und Metadaten zurückgegeben (viel größer). Wenn False, werden nur Werte zurückgegeben (effizienter).

  • Rückgabe: Wenn include_grid_data=True, vollständige Rasterdaten mit Metadaten (get-Antwort). Wenn False, ein Werte-Ergebnisobjekt von der Values-API (values.get-Antwort).

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

  • spreadsheet_id (String): Die Tabellenkalkulations-ID (aus der URL).

  • sheet (String): Name des Blatts/Tabs (z. B. „Sheet1“).

  • range (optionaler String): A1-Notation (z. B. 'A1:C10', 'Sheet1!B2:D'). Wenn nicht angegeben, werden alle Formeln im Blatt/Tab gelesen, das durch sheet angegeben ist.

  • Rückgabe: 2D-Array von Zellformeln (Array von Arrays) (values.get-Antwort).

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

  • spreadsheet_id (String): Die Tabellenkalkulations-ID (aus der URL).

  • sheet (String): Name des Blatts/Tabs (z. B. „Sheet1“).

  • range (String): A1-Notation des zu beschreibenden Bereichs (z. B. 'A1:C3').

  • data (Array von Arrays): 2D-Array von zu schreibenden Werten. Beispiel: [[1, 2, 3], ["a", "b", "c"]].

  • Rückgabe: Aktualisierungsergebnisobjekt (values.update-Antwort).

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

  • spreadsheet_id (String): Die Tabellenkalkulations-ID (aus der URL).

  • sheet (String): Name des Blatts/Tabs (z. B. „Sheet1“).

  • ranges (Objekt): Wörterbuch, das Bereichsstrings (A1-Notation) auf 2D-Arrays von Werten abbildet. Beispiel: { "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] }.

  • Rückgabe: Ergebnis der Operation (values.batchUpdate-Antwort).

• add_rows: Fügt leere Zeilen zu einem Blatt/Tab an einem angegebenen Index hinzu (einfügt).

  • spreadsheet_id (String): Die Tabellenkalkulations-ID (aus der URL).

  • sheet (String): Name des Blatts/Tabs (z. B. „Sheet1“).

  • count (Integer): Anzahl der einzufügenden leeren Zeilen.

  • start_row (optionaler Integer, Standard 0): 0-basierter Zeilenindex, an dem das Einfügen beginnen soll. Wenn nicht angegeben, wird standardmäßig 0 verwendet (fügt am Anfang ein).

  • Rückgabe: Ergebnis der Operation (batchUpdate-Antwort).

• list_sheets: Listet alle Blatt-/Tab-Namen innerhalb einer Tabellenkalkulation auf.

  • spreadsheet_id (String): Die Tabellenkalkulations-ID (aus der URL).

  • Rückgabe: Liste von Blatt-/Tab-Namensstrings. Beispiel: ["Sheet1", "Sheet2"].

• create_sheet: Fügt einer Tabellenkalkulation ein neues Blatt/Tab hinzu.

  • spreadsheet_id (String): Die Tabellenkalkulations-ID (aus der URL).

  • title (String): Name für das neue Blatt/Tab.

  • Rückgabe: Objekt mit den Eigenschaften des neuen Blatts.

• get_multiple_sheet_data: Ruft Daten aus mehreren Bereichen über möglicherweise verschiedene Tabellenkalkulationen in einem Aufruf ab.

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

  • Rückgabe: Liste von Objekten, die jeweils die Abfrageparameter und abgerufene data oder einen error enthalten. Jede data ist eine values.get-Antwort.

• get_multiple_spreadsheet_summary: Ruft Titel, Blatt-/Tab-Namen, Kopfzeilen und die ersten Zeilen für mehrere Tabellenkalkulationen ab.

  • spreadsheet_ids (Array von Strings): IDs der Tabellenkalkulationen (aus deren URLs).

  • rows_to_fetch (optionaler Integer, Standard 5): Wie viele Zeilen (einschließlich Kopfzeile) als Vorschau angezeigt werden sollen. Beispiel: 5.

  • Rückgabe: Liste von Zusammenfassungsobjekten für jede Tabellenkalkulation.

• share_spreadsheet: Teilt eine Tabellenkalkulation mit bestimmten Benutzern/E-Mails und Rollen.

  • spreadsheet_id (String): Die Tabellenkalkulations-ID (aus der URL).

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

  • send_notification (optionaler Boolean, Standard True): E-Mail-Benachrichtigungen an Empfänger senden.

  • Rückgabe: Wörterbuch mit successes- und failures-Listen.

• add_columns: Fügt leere Spalten zu einem Blatt/Tab an einem angegebenen Index hinzu (einfügt).

  • spreadsheet_id (String): Die Tabellenkalkulations-ID (aus der URL).

  • sheet (String): Name des Blatts/Tabs (z. B. „Sheet1“).

  • count (Integer): Anzahl der einzufügenden leeren Spalten.

  • start_column (optionaler Integer, Standard 0): 0-basierter Spaltenindex, an dem das Einfügen beginnen soll. Wenn nicht angegeben, wird standardmäßig 0 verwendet (fügt am Anfang ein).

  • Rückgabe: Ergebnis der Operation (batchUpdate-Antwort).

• copy_sheet: Dupliziert ein Blatt/Tab von einer Tabellenkalkulation in eine andere und benennt es optional um.

  • src_spreadsheet (String): Quell-Tabellenkalkulations-ID (aus der URL).

  • src_sheet (String): Quell-Blatt-/Tab-Name (z. B. „Sheet1“).

  • dst_spreadsheet (String): Ziel-Tabellenkalkulations-ID (aus der URL).

  • dst_sheet (String): Gewünschter Blatt-/Tab-Name in der Ziel-Tabellenkalkulation.

  • Rückgabe: Ergebnis der Kopier- und optionalen Umbenennungsoperationen.

• rename_sheet: Benennt ein vorhandenes Blatt/Tab um.

  • spreadsheet (String): Die Tabellenkalkulations-ID (aus der URL).

  • sheet (String): Aktueller Blatt-/Tab-Name (z. B. „Sheet1“).

  • new_name (String): Neuer Blatt-/Tab-Name (z. B. „Transactions“).

  • Rückgabe: Ergebnis der Operation (batchUpdate-Antwort).

• add_chart: Erstellt ein Diagramm in einer Google-Tabellenkalkulation aus angegebenen Daten.

  • spreadsheet_id (String): Die Tabellenkalkulations-ID (aus der URL).

  • sheet (String): Name des Blatts/Tabs, das die Daten enthält (z. B. „Sheet1“).

  • chart_type (String): Typ des zu erstellenden Diagramms. Optionen: COLUMN (vertikale Balken), BAR (horizontale Balken), LINE, AREA, PIE, SCATTER, COMBO, HISTOGRAM.

  • data_range (String): A1-Notation des Bereichs für die Diagrammdaten (z. B. „A1:C10“). Die erste Zeile wird als Kopfzeile behandelt.

  • title (optionaler String): Diagrammtitel.

  • x_axis_label (optionaler String): Beschriftung für die X-Achse (untere Achse). Nicht für Kreisdiagramme anwendbar.

  • y_axis_label (optionaler String): Beschriftung für die Y-Achse (linke Achse). Nicht für Kreisdiagramme anwendbar.

  • position_x (optionaler Integer, Standard 0): Horizontaler Positionsversatz in Pixeln von der oberen linken Ecke.

  • position_y (optionaler Integer, Standard 0): Vertikaler Positionsversatz in Pixeln von der oberen linken Ecke.

  • width (optionaler Integer, Standard 600): Breite des Diagramms in Pixeln.

  • height (optionaler Integer, Standard 400): Höhe des Diagramms in Pixeln.

  • Rückgabe: Ergebnisobjekt mit Erfolgsstatus, Diagramm-ID und Operationsdetails.

MCP-Ressourcen:

• spreadsheet://{spreadsheet_id}/info: Ruft grundlegende Metadaten über eine Google-Tabellenkalkulation ab.

  • Rückgabe: JSON-String mit Tabellenkalkulationsinformationen.

☁️ Google Cloud Platform Einrichtung (detailliert)

Diese Einrichtung ist erforderlich, bevor der Server ausgeführt wird.

1. GCP-Projekt erstellen/auswählen: 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 eine der folgenden Authentifizierungsmethoden auswählen (Service Account wird empfohlen).

🔑 Authentifizierung & Umgebungsvariablen (detailliert)

Der Server benötigt Anmeldeinformationen, um auf Google-APIs zuzugreifen. Wählen Sie eine Methode:

Weitere Informationen zu den unten verwendeten IDs finden Sie im ID-Referenzhandbuch.

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

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

• Schritte:

  1. Service Account erstellen: In der GCP-Konsole -> „IAM & Verwaltung“ -> „Dienstkonten“.

     • Klicken Sie auf „+ DIENSTKONTO ERSTELLEN“. Benennen Sie es (z. B. mcp-sheets-service).

     • Rollen zuweisen: Fügen Sie die Rolle Editor für breiten Zugriff hinzu oder granularere Rollen (wie roles/drive.file und spezifische Sheets-Rollen) für strengere Berechtigungen.

     • Klicken Sie auf „Fertig“. Suchen Sie das Konto, 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“ -> „Freigeben“.

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

     • Gewähren Sie Editor-Zugriff. Deaktivieren Sie „Personen benachrichtigen“. Klicken Sie auf „Freigeben“.

  3. Umgebungsvariablen festlegen:

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

     • DRIVE_FOLDER_ID: Die ID des freigegebenen Google-Drive-Ordners. (Siehe Ultra-Schnellstart für betriebssystemspezifische Beispiele)

Methode B: OAuth 2.0 (interaktiv / persönliche Nutzung) 🧑💻

• Warum? Für persönliche Nutzung oder lokale Entwicklung, bei der ein interaktiver Browser-Login akzeptabel ist.

• Schritte:

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

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

  3. Umgebungsvariablen festlegen:

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

     • TOKEN_PATH: Pfad zum Speichern des Benutzer-Refresh-Tokens nach der ersten Anmeldung (Standard: token.json). Muss beschreibbar sein.

Methode C: Direkte Anmeldedaten-Injektion (fortgeschritten) 🔒

• Warum? Nützlich in Umgebungen wie Docker, Kubernetes oder CI/CD, in denen die Verwaltung von Dateien schwierig ist, aber Umgebungsvariablen einfach/sicher sind. Vermeidet Dateisystemzugriff.

• Wie? Anstatt einen Pfad zur Anmeldedatei anzugeben, wird der Inhalt der Datei, Base64-kodiert, direkt in einer Umgebungsvariable bereitgestellt.

• Schritte:

  1. Holen Sie sich Ihre JSON-Anmeldedatei (entweder Service-Account-Schlüssel oder 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

     • (Vorsicht): Vermeiden Sie es, sensible Anmeldedaten in nicht vertrauenswürdige Online-Encoder einzufügen.

  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..."

Methode D: Application Default Credentials (ADC) 🌐

• Warum? Ideal für Google-Cloud-Umgebungen (GKE, Compute Engine, Cloud Run) und lokale Entwicklung mit gcloud auth application-default login. Keine expliziten Anmeldedateien erforderlich.

• Wie? Verwendet die Application Default Credentials-Kette von Google, um Anmeldedaten automatisch aus mehreren Quellen zu ermitteln.

• ADC-Suchreihenfolge:

  1. GOOGLE_APPLICATION_CREDENTIALS-Umgebungsvariable (Pfad zum Service-Account-Schlüssel) - Googles Standardvariable

  2. gcloud auth application-default login-Anmeldedaten (lokale Entwicklung)

  3. Angehängter Service-Account vom Metadatenserver (GKE, Compute Engine usw.)

• Einrichtung:

  • Lokale Entwicklung:

    1. Führen Sie gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive einmal aus

    2. Legen Sie ein Quota-Projekt fest: gcloud auth application-default set-quota-project <project_id> (ersetzen Sie <project_id> durch Ihre Google-Cloud-Projekt-ID)

  • Google Cloud: Hängen Sie einen Service-Account an Ihre Compute-Ressource an

  • Umgebungsvariable: Setzen Sie GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json (Googles Standard)

• Keine zusätzlichen Umgebungsvariablen erforderlich - ADC wird automatisch als Fallback verwendet, wenn andere Methoden fehlschlagen.

Hinweis: GOOGLE_APPLICATION_CREDENTIALS ist Googles offizielle Standard-Umgebungsvariable, während SERVICE_ACCOUNT_PATH spezifisch für diesen MCP-Server ist. Wenn Sie GOOGLE_APPLICATION_CREDENTIALS setzen, findet ADC diese automatisch.

Authentifizierungspriorität & Zusammenfassung

Der Server prüft die Anmeldedaten in dieser Reihenfolge:

1. CREDENTIALS_CONFIG (Base64-Inhalt)

2. SERVICE_ACCOUNT_PATH (Pfad zur Service-Account-JSON)

3. CREDENTIALS_PATH (Pfad zur OAuth-JSON) - löst den interaktiven Ablauf aus, wenn das Token fehlt/abgelaufen ist

4. Application Default Credentials (ADC) - automatischer Fallback

Zusammenfassung der Umgebungsvariablen:

⚙️ Ausführen des Servers (Detailliert)

Siehe den ID-Referenzleitfaden für weitere Informationen zu den unten verwendeten IDs.

Methode 1: Verwendung von uvx (Empfohlen für Benutzer)

Wie im Ultra-Schnellstart gezeigt, ist dies der einfachste Weg. Setzen Sie die Umgebungsvariablen und führen Sie dann aus:

uvx mcp-google-sheets@latest

uvx übernimmt das Abrufen und Ausführen des Pakets temporär.

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

Wenn Sie den Code ändern möchten:

1. Klonen: git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets (Verwenden Sie die tatsächliche URL)

2. Umgebungsvariablen setzen: Wie oben beschrieben.

3. Mit uv ausführen: (Verwendet den lokalen Code)

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

Methode 3: Docker (SSE-Transport)

Führen Sie den Server in einem Container mit dem enthaltenen Dockerfile aus:

# Build the image
docker build -t mcp-google-sheets .

# Run (SSE on port 8000)
# NOTE: Prefer CREDENTIALS_CONFIG (Base64 credentials content) in containers.
docker run --rm -p 8000:8000 ^
  -e HOST=0.0.0.0 ^
  -e PORT=8000 ^
  -e CREDENTIALS_CONFIG=YOUR_BASE64_CREDENTIALS ^
  -e DRIVE_FOLDER_ID=YOUR_DRIVE_FOLDER_ID ^
  mcp-google-sheets

• Verwenden Sie CREDENTIALS_CONFIG anstelle von SERVICE_ACCOUNT_PATH in Docker, um das Mounten von Geheimnissen als Dateien zu vermeiden.

• Der Container startet mit --transport sse und lauscht auf HOST/PORT. Weisen Sie Ihren MCP-Client mit SSE-Transport auf http://localhost:8000.

🔌 Verwendung mit Claude Desktop

Fügen Sie die Serverkonfiguration zu claude_desktop_config.json unter mcpServers hinzu. Wählen Sie den Block, der zu Ihrer Einrichtung passt:

Siehe den ID-Referenzleitfaden für weitere Informationen zu den unten verwendeten IDs.

⚠️ Wichtige Hinweise:

• 🍎 macOS-Benutzer: Verwenden Sie den vollständigen Pfad: "/Users/yourusername/.local/bin/uvx" anstelle von nur "uvx"

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

🍎 macOS-Hinweis: Wenn Sie einen spawn uvx ENOENT-Fehler erhalten, verwenden Sie den vollständigen Pfad zu uvx:

{
  "mcpServers": {
    "google-sheets": {
      "command": "/Users/yourusername/.local/bin/uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

Ersetzen Sie yourusername durch Ihren tatsächlichen Benutzernamen.

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "CREDENTIALS_PATH": "/full/path/to/your/credentials.json",
        "TOKEN_PATH": "/full/path/to/your/token.json"
      }
    }
  }
}

Hinweis: Beim ersten Gebrauch öffnet sich möglicherweise ein Browser für die Google-Anmeldung. Stellen Sie sicher, dass TOKEN_PATH beschreibbar ist.

🍎 macOS-Hinweis: Wenn Sie einen spawn uvx ENOENT-Fehler erhalten, ersetzen Sie "command": "uvx" durch "command": "/Users/yourusername/.local/bin/uvx" (ersetzen Sie yourusername durch Ihren tatsächlichen Benutzernamen).

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "CREDENTIALS_CONFIG": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi...",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

Hinweis: Fügen Sie die vollständige Base64-Zeichenfolge für CREDENTIALS_CONFIG ein. DRIVE_FOLDER_ID wird weiterhin für den Service-Account-Ordnerkontext benötigt.

🍎 macOS-Hinweis: Wenn Sie einen spawn uvx ENOENT-Fehler erhalten, ersetzen Sie "command": "uvx" durch "command": "/Users/yourusername/.local/bin/uvx" (ersetzen Sie yourusername durch Ihren tatsächlichen Benutzernamen).

Option 1: Mit GOOGLE_APPLICATION_CREDENTIALS

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

Option 2: Mit gcloud auth (keine Umgebungsvariablen erforderlich)

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {}
    }
  }
}

Voraussetzungen:

1. Führen Sie zuerst gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive aus.

2. Legen Sie das Quota-Projekt fest: gcloud auth application-default set-quota-project <project_id>

🍎 macOS-Hinweis: Wenn Sie einen spawn uvx ENOENT-Fehler erhalten, ersetzen Sie "command": "uvx" durch "command": "/Users/yourusername/.local/bin/uvx" (ersetzen Sie yourusername durch Ihren tatsächlichen Benutzernamen).

{
  "mcpServers": {
    "mcp-google-sheets-local": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/mcp-google-sheets",
        "mcp-google-sheets"
      ],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/path/to/your/mcp-google-sheets/service_account.json",
        "DRIVE_FOLDER_ID": "your_drive_folder_id_here"
      }
    }
  }
}

Hinweis: Verwenden Sie das --directory-Flag, um den Projektpfad anzugeben, und passen Sie die Pfade an Ihren tatsächlichen Arbeitsbereich an.

💬 Beispiel-Prompts für Claude

Sobald die Verbindung hergestellt ist, versuchen Sie Prompts wie:

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

• "Erstelle eine neue Tabelle mit dem Titel 'Quartalsverkaufsbericht Q3 2024'."

• "Hole in der Tabelle 'Quartalsverkaufsbericht' die Daten aus Sheet1, Bereich A1 bis E10."

• "Füge ein neues Blatt mit dem Namen 'Zusammenfassung' zur Tabelle mit der ID 1aBcDeFgHiJkLmNoPqRsTuVwXyZ hinzu."

• "Aktualisiere in meiner Tabelle 'Projektaufgaben', Blatt 'Aufgaben', Zelle B2 auf 'In Bearbeitung'."

• "Füge diese Zeilen zum Blatt 'Protokoll' in der Tabelle XYZ hinzu: [['2024-07-31', 'Aufgabe A abgeschlossen'], ['2024-08-01', 'Aufgabe B gestartet']]"

• "Erstelle eine Zusammenfassung der Tabellen 'Verkaufsdaten' und 'Inventarzählung'."

• "Teile die Tabelle 'Team-Urlaubsplan' mit team@example.com als Leser und manager@example.com als Autor. Sende keine Benachrichtigungen."

• "Erstelle ein Säulendiagramm in meiner Tabelle 'Verkaufsbericht', das den monatlichen Umsatz aus den Daten im Bereich A1:B13 zeigt."

• "Füge dem Blatt 'Marktanalyse' ein Kreisdiagramm mit Daten aus A1:B5 mit dem Titel 'Marktanteil nach Produkt' hinzu."

• "Erstelle in der Tabelle abc123 ein Liniendiagramm auf Sheet1 aus dem Bereich A1:C10 mit dem Titel 'Wachstumstrends' und den Beschriftungen 'Monat' und 'Umsatz'."

🆔 ID-Referenzleitfaden

Verwenden Sie den folgenden Referenzleitfaden, um die verschiedenen IDs zu finden, auf die in der gesamten Dokumentation verwiesen wird:

Google Cloud Project ID:
  https://console.cloud.google.com/apis/dashboard?project=sheets-mcp-server-123456
                                                          └───── Project ID ─────┘

Google Drive Folder ID:
  https://drive.google.com/drive/u/0/folders/1xcRQCU9xrNVBPTeNzHqx4hrG7yR91WIa
                                             └────────── Folder ID ──────────┘

Google Sheets Spreadsheet ID:
  https://docs.google.com/spreadsheets/d/25_-_raTaKjaVxu9nJzA7-FCrNhnkd3cXC54BPAOXemI/edit
                                         └───────────── Spreadsheet ID ─────────────┘

🤝 Mitwirken

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

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert - siehe die Datei LICENSE für Details.

🙏 Danksagungen

• Erstellt mit FastMCP.

• Inspiriert von kazz187/mcp-google-spreadsheet.

• Verwendet Google-API-Python-Client-Bibliotheken.