braze-mcp-server 1.2.0

Braze MCP Server - Model Context Protocol server for Braze REST API access

Braze MCP Server

Braze Model Context Protocol (MCP) server is a secure connection that lets AI tools like Claude and Cursor access non-PII Braze data to answer questions, analyze trends, and provide insights. It is primarily read-focused and also supports specific write actions such as media library asset creation when configured. For more general information, see Braze MCP server.

Additional resources

• Setting up Braze MCP server: A more-detailed alternative to the following Quick start section (includes troubleshooting).
• Using Braze MCP server: Best practices and usage examples for tools like Claude and Cursor.
• Available API functions: List of functions LLMs can use retrieve data from Braze.

Quick start

Step 1: Create an API key

In Braze, go to Settings > APIs and Identifiers > API Keys and create a new key with some or all the following permissions.

Category	Endpoint	Required Permission
Campaigns	/campaigns/data_series	campaigns.data_series
Campaigns	/campaigns/details	campaigns.details
Campaigns	/campaigns/list	campaigns.list
Campaigns	/sends/data_series	sends.data_series
Canvas	/canvas/data_series	canvas.data_series
Canvas	/canvas/data_summary	canvas.data_summary
Canvas	/canvas/details	canvas.details
Canvas	/canvas/list	canvas.list
Catalogs	/catalogs	catalogs.get
Catalogs	/catalogs/{catalog_name}/items	catalogs.get_items
Catalogs	/catalogs/{catalog_name}/items/{item_id}	catalogs.get_item
Cloud Data Ingestion	/cdi/integrations	cdi.integration_list
Cloud Data Ingestion	/cdi/integrations/{integration_id}/job_sync_status	cdi.integration_job_status
Content Blocks	/content_blocks/list	content_blocks.list
Content Blocks	/content_blocks/info	content_blocks.info
Content Blocks (write)	/content_blocks/create	content_blocks.create
Content Blocks (write)	/content_blocks/update	content_blocks.update
Custom Attributes	/custom_attributes	custom_attributes.get
Events	/events/list	events.list
Events	/events/data_series	events.data_series
Events	/events	events.get
KPIs	/kpi/new_users/data_series	kpi.new_users.data_series
KPIs	/kpi/dau/data_series	kpi.dau.data_series
KPIs	/kpi/mau/data_series	kpi.mau.data_series
KPIs	/kpi/uninstalls/data_series	kpi.uninstalls.data_series
Messages	/messages/scheduled_broadcasts	messages.schedule_broadcasts
Media Library (write)	/media_library/create	media_library.create
Preference Center	/preference_center/v1/list	preference_center.list
Preference Center	/preference_center/v1/{preferenceCenterExternalID}	preference_center.get
Purchases	/purchases/product_list	purchases.product_list
Purchases	/purchases/revenue_series	purchases.revenue_series
Purchases	/purchases/quantity_series	purchases.quantity_series
Segments	/segments/list	segments.list
Segments	/segments/data_series	segments.data_series
Segments	/segments/details	segments.details
Sends	/sends/data_series	sends.data_series
Sessions	/sessions/data_series	sessions.data_series
SDK Authentication Keys	/app_group/sdk_authentication/keys	sdk_authentication.keys
Subscription	/subscription/status/get	subscription.status.get
Subscription	/subscription/user/status	subscription.groups.get
Templates	/templates/email/list	templates.email.list
Templates	/templates/email/info	templates.email.info
Templates (write)	/templates/email/create	templates.email.create
Templates (write)	/templates/email/update	templates.email.update

[!WARNING] Do not reuse an existing API key—create one specifically for your MCP client. Assign least-privilege, non-PII permissions only. Write-capable scopes (rows marked "(write)" above: media_library.create, templates.email.create, templates.email.update, content_blocks.create, content_blocks.update) let agents create or modify content in your Braze workspace — only grant the specific write scopes you intend the agent to exercise, and consider a sandbox workspace for testing them.

[!NOTE] For /media_library/create, the server supports either asset_url or base64-encoded file uploads (asset_file_base64). Uploaded media must follow Braze media library constraints (for example image type and size limits, including the 5 MB image limit documented by Braze).

Step 2: Install uv

Run the following command to install uv, a command-line tool by Astral for dependency management and Python package handling:

MacOS and Linux

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

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 3: Configure your MCP client

Configure your MCP client using our pre-provided configuration file.

Claude

1. In Claude Desktop, go to Settings > Developer > Edit Config, then add the following snippet:

   {
     "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"
         }
       }
     }
   }
   

2. Save the configuration and restart Claude Desktop.
3. To verify your connection, try asking a question like "List my Braze campaigns".

Cursor

1. In Cursor, go to Settings > Tools and Integrations > MCP Tools > Add Custom MCP, then add the following snippet:

   {
     "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"
         }
       }
     }
   }
   

2. When you're finished, save the configuration and restart Cursor.
3. To verify your connection, try using the provided MCP tools to interact with your Braze data.

Build MCP Bundle (.mcpb)

You can package this server as an MCP Bundle for easy installation in compatible MCP clients.

Prerequisites

• Node.js and npm installed (for MCPB CLI)
• uv installed and on PATH (required at runtime by the server)
  • macOS/Linux:

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

  • Ensure ~/.local/bin is on your PATH

Install MCPB CLI

npm install -g @anthropic-ai/mcpb

Package the bundle

From the repository root:

# Create source directory for packaging
mkdir -p dist/mcpb-source
cp -r src/ dist/mcpb-source/
cp pyproject.toml dist/mcpb-source/
cp uv.lock dist/mcpb-source/
cp manifest.json dist/mcpb-source/
cp README.md dist/mcpb-source/

# Generate the MCPB bundle
mcpb pack dist/mcpb-source/ dist/braze-mcp-server-source.mcpb

This creates a file at:

./dist/braze-mcp-server-source.mcpb

Install in MCP Clients

Option 1: Claude Desktop (Recommended)

1. Open the .mcpb file directly with Claude Desktop
2. Claude will automatically handle installation and prompt for configuration
3. When prompted, enter:
   • BRAZE_API_KEY: your Braze API key (read‑only permissions only)
   • BRAZE_BASE_URL: your Braze REST endpoint (e.g., https://rest.iad-01.braze.com)
4. Restart Claude Desktop if the server doesn't start automatically

Option 2: Other MCP Clients (Cursor, etc.)

1. Unpack the bundle:

   mcpb unpack dist/braze-mcp-server-source.mcpb /path/to/install
   

2. Configure your MCP client to use the unpacked server
3. Set environment variables in your client configuration

Troubleshooting

MCPB CLI Issues

• "mcpb: command not found":
  • Install MCPB CLI: npm install -g @anthropic-ai/mcpb
  • Verify installation: mcpb --version

Server Runtime Issues

• "spawn uvx ENOENT" or "uvx not found":
  • Install uv using the command above
  • Make sure ~/.local/bin is on PATH

Bundle Installation Issues

• "Manifest validation failed":
  • Check that manifest.json is valid JSON
  • Ensure all required fields are present in the manifest
• "Cannot open .mcpb file":
  • Verify your MCP client supports MCPB bundles
  • Try manual installation with mcpb unpack

API Connection Issues

• "Invalid API key" or "Authentication failed":
  • Verify your BRAZE_API_KEY is correct and has read permissions
  • Check that BRAZE_BASE_URL matches your Braze instance
• "Connection timeout":
  • Verify your Braze instance URL is correct
  • Check network connectivity and firewall settings

Release flow

See the Release Process section in DEVELOPMENT.md for the canonical steps, including the two version-bump locations (pyproject.toml and manifest.json) and how the Test PyPI / PyPI workflows are triggered.

Disclaimer

The Model Context Protocol (MCP) is a newly introduced open-source protocol that may be susceptible to security issues or vulnerabilities at this time.

Braze MCP Server setup code and instructions are provided by Braze “as is” and without any warranties, and customers use it at their own risk. Braze shall not be responsible for any consequences arising from improper setup, misuse of the MCP, or any potential security issues that may arise. Braze strongly encourages customers to review their configurations carefully and to follow the outlined guidelines to reduce risks associated with the integrity and security of their Braze environment.

For assistance or clarification, please contact [e-mail].