Skip to content

Einrichtung des Braze MCP-Servers

Erfahren Sie, wie Sie den Braze MCP-Server einrichten, um mit Ihren Braze-Daten mithilfe von Tools für natürliche Sprache wie Claude und Cursor zu interagieren. Weitere allgemeine Informationen finden Sie unter Braze MCP-Server.

Voraussetzungen

Bevor Sie beginnen, benötigen Sie Folgendes:

Voraussetzung Beschreibung
Braze-API-Schlüssel Ein Braze-API-Schlüssel mit den erforderlichen Berechtigungen. Sie erstellen einen neuen Schlüssel, wenn Sie Ihren Braze MCP-Server einrichten.
MCP-Client Claude, Cursor und Google Gemini CLI werden offiziell unterstützt. Sie benötigen ein Konto für einen dieser Clients, um den Braze MCP-Server nutzen zu können.
Terminal Eine Terminal-App, mit der Sie Befehle ausführen und Tools installieren können. Verwenden Sie Ihre bevorzugte Terminal-App oder die auf Ihrem Computer vorinstallierte.

Einrichtung des Braze MCP-Servers

1. Schritt: uv installieren

Installieren Sie zunächst uv—ein Befehlszeilentool von Astral für die Abhängigkeitsverwaltung und die Handhabung von Python-Paketen.

Öffnen Sie Ihre Terminal-Anwendung, fügen Sie den folgenden Befehl ein und drücken Sie Enter.

1

curl -LsSf https://astral.sh/uv/install.sh | sh

Die Ausgabe sieht in etwa wie folgt aus:

1
2
3
4
5
6
7
8

$ curl -LsSf https://astral.sh/uv/install.sh | sh

downloading uv 0.8.9 aarch64-apple-darwin
no checksums to verify
installing to /Users/Isaiah.Robinson/.local/bin
  uv
  uvx
everything's installed!

Öffnen Sie Windows PowerShell, fügen Sie den folgenden Befehl ein und drücken Sie Enter.

1

irm https://astral.sh/uv/install.ps1 | iex

Die Ausgabe sieht in etwa wie folgt aus:

1
2
3
4
5
6
7
8

PS C:\Users\YourUser> irm https://astral.sh/uv/install.ps1 | iex

Downloading uv 0.8.9 (x86_64-pc-windows-msvc)
no checksums to verify
installing to C:\Users\YourUser\.local\bin
  uv.exe
  uvx.exe
everything's installed!

2. Schritt: API-Schlüssel erstellen

Der Braze MCP-Server umfasst sowohl Lese- als auch Schreib-Endpunkte. Sie geben keine Daten aus Braze-Nutzerprofilen zurück. Schreib-Endpunkte ermöglichen es Agenten, Inhalte in Ihrem Workspace zu erstellen oder zu aktualisieren.

So erstellen Sie Ihren API-Schlüssel:

  1. Navigieren Sie zu Einstellungen > APIs und Bezeichner > API-Schlüssel.
  2. Erstellen Sie einen neuen Schlüssel.
  3. Weisen Sie Ihrem Schlüssel einige oder alle der folgenden Berechtigungen zu.
Liste der unterstützten Berechtigungen

Campaigns

Endpunkt Erforderliche Berechtigung
/campaigns/data_series campaigns.data_series
/campaigns/details campaigns.details
/campaigns/list campaigns.list
/sends/data_series sends.data_series

Canvas

Endpunkt Erforderliche Berechtigung
/canvas/data_series canvas.data_series
/canvas/data_summary canvas.data_summary
/canvas/details canvas.details
/canvas/list canvas.list

Kataloge

Endpunkt Erforderliche Berechtigung
/catalogs catalogs.get
/catalogs/{catalog_name}/items catalogs.get_items
/catalogs/{catalog_name}/items/{item_id} catalogs.get_item

Cloud-Datenaufnahme

Endpunkt Erforderliche Berechtigung
/cdi/integrations cdi.integration_list
/cdi/integrations/{integration_id}/job_sync_status cdi.integration_job_status

Content Blocks

Die Berechtigungen content_blocks.create und content_blocks.update sind Schreibberechtigungen. Fügen Sie sie nur hinzu, wenn Ihr Agent Content Blocks in Ihrem Workspace erstellen oder aktualisieren soll.

Endpunkt Erforderliche Berechtigung
/content_blocks/list content_blocks.list
/content_blocks/info content_blocks.info
/content_blocks/create content_blocks.create
/content_blocks/update content_blocks.update

Angepasste Attribute

Endpunkt Erforderliche Berechtigung
/custom_attributes custom_attributes.get

Ereignisse

Endpunkt Erforderliche Berechtigung
/events/list events.list
/events/data_series events.data_series
/events events.get

KPIs

Endpunkt Erforderliche Berechtigung
/kpi/new_users/data_series kpi.new_users.data_series
/kpi/dau/data_series kpi.dau.data_series
/kpi/mau/data_series kpi.mau.data_series
/kpi/uninstalls/data_series kpi.uninstalls.data_series

Medienbibliothek

Die Berechtigung media_library.create ist eine Schreibberechtigung. Fügen Sie sie nur hinzu, wenn Ihr Agent Assets in Ihre Medienbibliothek hochladen soll.

Endpunkt Erforderliche Berechtigung
/media_library/create media_library.create

Nachrichten

Endpunkt Erforderliche Berechtigung
/messages/scheduled_broadcasts messages.schedule_broadcasts

Präferenzzentrum

Endpunkt Erforderliche Berechtigung
/preference_center/v1/list preference_center.list
/preference_center/v1/{preferenceCenterExternalID} preference_center.get

Käufe

Endpunkt Erforderliche Berechtigung
/purchases/product_list purchases.product_list
/purchases/revenue_series purchases.revenue_series
/purchases/quantity_series purchases.quantity_series

Segments

Endpunkt Erforderliche Berechtigung
/segments/list segments.list
/segments/data_series segments.data_series
/segments/details segments.details

Sendungen

Endpunkt Erforderliche Berechtigung
/sends/data_series sends.data_series

Sitzungen

Endpunkt Erforderliche Berechtigung
/sessions/data_series sessions.data_series

SDK-Authentifizierungsschlüssel

Endpunkt Erforderliche Berechtigung
/app_group/sdk_authentication/keys sdk_authentication.keys

Abo

Endpunkt Erforderliche Berechtigung
/subscription/status/get subscription.status.get
/subscription/user/status subscription.groups.get

Templates

Die Berechtigungen templates.email.create und templates.email.update sind Schreibberechtigungen. Fügen Sie sie nur hinzu, wenn Ihr Agent E-Mail-Templates in Ihrem Workspace erstellen oder aktualisieren soll.

Endpunkt Erforderliche Berechtigung
/templates/email/list templates.email.list
/templates/email/info templates.email.info
/templates/email/create templates.email.create
/templates/email/update templates.email.update

3. Schritt: Bezeichner und Endpunkt abrufen

Wenn Sie Ihren MCP-Client konfigurieren, benötigen Sie den Bezeichner Ihres API-Schlüssels und den REST-Endpunkt Ihres Workspaces. Um diese Informationen abzurufen, kehren Sie zur Seite API-Schlüssel im Dashboard zurück—lassen Sie diese Seite geöffnet, damit Sie im nächsten Schritt darauf zurückgreifen können.

Die Seite „API-Schlüssel“ in Braze mit einem neu erstellten API-Schlüssel und dem REST-Endpunkt der Nutzer:innen.

4. Schritt: MCP-Client konfigurieren

Konfigurieren Sie Ihren MCP-Client mithilfe der bereitgestellten Konfigurationsdatei.

Richten Sie Ihren MCP-Server mithilfe des Claude Desktop-Konnektor-Verzeichnisses ein.

  1. Gehen Sie in Claude Desktop zu Settings > Connectors > Browse Connectors > Desktop Extensions > Braze MCP Server > Install.
  2. Geben Sie Ihren API-Schlüssel und Ihre Basis-URL ein.
  3. Speichern Sie die Konfiguration und starten Sie Claude Desktop neu.

Gehen Sie in Cursor zu Settings > Tools and Integrations > MCP Tools > Add Custom MCP und fügen Sie das folgende Snippet hinzu:

1
2
3
4
5
6
7
8
9
10
11
12

{
  "mcpServers": {
    "braze": {
      "command": "uvx",
      "args": ["--native-tls", "braze-mcp-server@latest"],
      "env": {
        "BRAZE_API_KEY": "your-braze-api-key",
        "BRAZE_BASE_URL": "your-braze-endpoint-url"
      }
    }
  }
}

Ersetzen Sie key-identifier und rest-endpoint durch die entsprechenden Werte von der Seite API-Schlüssel in Braze. Ihre Konfiguration sollte in etwa wie folgt aussehen:

1
2
3
4
5
6
7
8
9
10
11
12

{
  "mcpServers": {
    "braze": {
      "command": "uvx",
      "args": ["--native-tls", "braze-mcp-server@latest"],
      "env": {
        "BRAZE_API_KEY": "2e8b-3c6c-d12e-bd75-4f0e2a8e5c71",
        "BRAZE_BASE_URL": "https://torchie.braze.com"
      }
    }
  }
}

Wenn Sie fertig sind, speichern Sie die Konfiguration und starten Sie Cursor neu.

Gemini CLI liest Nutzer:innen-Einstellungen aus ~/.gemini/settings.json. Falls diese Datei nicht vorhanden ist, können Sie sie erstellen, indem Sie Folgendes in Ihrem Terminal ausführen:

1
2

mkdir -p ~/.gemini
nano ~/.gemini/settings.json

Ersetzen Sie als Nächstes yourname durch den genauen String vor @BZXXXXXXXX in Ihrer Terminal-Eingabeaufforderung. Ersetzen Sie dann key-identifier und rest-endpoint durch die entsprechenden Werte von der Seite API-Schlüssel in Braze.

Ihre Konfiguration sollte in etwa wie folgt aussehen:

1
2
3
4
5
6
7
8
9
10
11
12

{
  "mcpServers": {
    "braze": {
      "command": "/Users/yourname/.local/bin/uvx",
      "args": ["--native-tls", "braze-mcp-server@latest"],
      "env": {
        "BRAZE_API_KEY": "2e8b-3c6c-d12e-bd75-4f0e2a8e5c71",
        "BRAZE_BASE_URL": "https://torchie.braze.com"
      }
    }
  }
}

Wenn Sie fertig sind, speichern Sie die Konfiguration und starten Sie Gemini CLI neu. Führen Sie anschließend in Gemini die folgenden Befehle aus, um zu überprüfen, ob der Braze MCP-Server aufgeführt ist und die Tools und das Schema zur Verwendung verfügbar sind:

1
2
3
4

gemini
/mcp
/mcp desc
/mcp schema

Sie sollten den braze-Server mit den verfügbaren Tools und Schemata aufgelistet sehen.

5. Schritt: Test-Prompt senden

Nachdem Sie den Braze MCP-Server eingerichtet haben, senden Sie einen Test-Prompt an Ihren MCP-Client. Weitere Beispiele und Best Practices finden Sie unter Verwendung des Braze MCP-Servers.

Beispiel-Prompt: What are my available Braze functions? Beispielantwort: Hat list_functions verwendet und die verfügbaren Braze MCP-Funktionskategorien zurückgegeben.

Beispiel-Prompt: What are my available Braze functions? Beispielantwort: Hat list_functions abgefragt und Funktionen wie get_canvas_list aufgelistet.

Beispiel-Prompt: What are my available Braze functions? Beispielantwort: Hat list_functions in Gemini CLI abgefragt und verfügbare Braze MCP-Funktionskategorien sowie Beispielfunktionen zurückgegeben.

Fehlerbehebung

Terminalfehler

uvx-Befehl nicht gefunden

Wenn Sie die Fehlermeldung erhalten, dass der uvx-Befehl nicht gefunden wurde, installieren Sie uv erneut und starten Sie Ihr Terminal neu.

1

curl -LsSf https://astral.sh/uv/install.sh | sh

spawn uvx ENOENT-Fehler

Wenn Sie spawn uvx ENOENT-Fehler erhalten, müssen Sie möglicherweise den Dateipfad in der Konfigurationsdatei Ihres Clients aktualisieren. Öffnen Sie zunächst Ihr Terminal und führen Sie den folgenden Befehl aus:

1

which uvx

Der Befehl sollte eine Nachricht ähnlich der folgenden zurückgeben:

1

/Users/alex-lee/.local/bin/uvx

Kopieren Sie die Nachricht in Ihre Zwischenablage und öffnen Sie die Konfigurationsdatei Ihres Clients. Ersetzen Sie "command": "uvx" durch den kopierten Pfad und starten Sie anschließend Ihren Client neu. Zum Beispiel:

1

"command": "/Users/alex-lee/.local/bin/uvx"

Paketinstallation schlägt fehl

Wenn die Paketinstallation fehlschlägt, versuchen Sie stattdessen, eine bestimmte Python-Version zu installieren.

1

uvx --python 3.12 braze-mcp-server@latest

Client-Konfiguration

„Diese Erweiterung ist nicht mit Ihrem Gerät kompatibel“

Wenn dieser Fehler bei der Installation der Braze MCP-Server-Erweiterung angezeigt wird, kann dies auf Folgendes hinweisen:

  • Ihr Gerät erfüllt die Anforderungen nicht: Einige MCP-Server-Erweiterungen erfordern bestimmte Betriebssystemversionen oder Hardware.
  • Fehlende Entwicklertools (nur macOS): Unter macOS benötigt die Installation der Erweiterung Befehlszeilen-Entwicklertools, um Python-Befehle auszuführen. Wenn diese Tools nicht installiert sind, schlägt die Installation mit diesem Fehler fehl.

Um die Befehlszeilen-Entwicklertools unter macOS zu installieren, führen Sie Folgendes in Ihrem Terminal aus:

1

xcode-select --install

Starten Sie nach Abschluss der Installation Ihren MCP-Client neu und versuchen Sie erneut, die Erweiterung zu installieren.

MCP-Client kann den Braze-Server nicht finden

  1. Überprüfen Sie, ob die Syntax Ihrer MCP-Client-Konfiguration korrekt ist.
  2. Starten Sie Ihren MCP-Client nach Konfigurationsänderungen neu.
  3. Überprüfen Sie, ob uvx in Ihrem System-PATH enthalten ist.

Authentifizierungsfehler

  1. Überprüfen Sie, ob Ihr BRAZE_API_KEY korrekt und aktiv ist.
  2. Stellen Sie sicher, dass Ihre BRAZE_BASE_URL mit Ihrer Braze-Instanz übereinstimmt.
  3. Überprüfen Sie, ob Ihr API-Schlüssel über die erforderlichen Berechtigungen verfügt.

Verbindungs-Timeouts oder Netzwerkfehler

  1. Überprüfen Sie, ob Ihre BRAZE_BASE_URL für Ihre Instanz korrekt ist.
  2. Überprüfen Sie Ihre Netzwerkverbindung und Firewall-Einstellungen.
  3. Stellen Sie sicher, dass Sie HTTPS in Ihrer Basis-URL verwenden.

Haftungsausschluss

Das Model Context Protocol (MCP) ist ein neu eingeführtes Open-Source-Protokoll, das zum gegenwärtigen Zeitpunkt möglicherweise anfällig für Sicherheitsprobleme oder Schwachstellen ist.

Der Braze MCP Server-Einrichtungscode und die Anweisungen werden von Braze „wie besehen” und ohne jegliche Gewährleistung bereitgestellt. Die Nutzung erfolgt auf eigenes Risiko der Kund:innen. Braze übernimmt keine Verantwortung für Konsequenzen, die sich aus einer unsachgemäßen Einrichtung, einer missbräuchlichen Verwendung des MCP oder möglichen Sicherheitsproblemen ergeben. Braze empfiehlt seinen Kund:innen dringend, ihre Konfigurationen sorgfältig zu überprüfen und die dargelegten Richtlinien zu befolgen, um Risiken im Zusammenhang mit der Integrität und Sicherheit ihrer Braze-Umgebung zu minimieren.

Für Unterstützung oder Erläuterungen kontaktieren Sie bitte den Braze Support.
New Stuff!