Skip to content

Setting up Braze MCP server

Learn how to set up Braze MCP server, so you can interact with your Braze data through natural language using tools like Claude and Cursor. For more general information, see Braze MCP server.

Prerequisites

Before you start, you’ll need the following:

Setting up Braze MCP server

Step 1: Create API key

Braze MCP server supports 38 read-only endpoints that do not typically return Personally Identifiable Information (PII) data. Go to Settings > APIs and Identifiers > API Keys and create a new key with some or all the following permissions.

List of read-only, non-PII permissions

Campaigns

Canvas

Catalogs

Cloud Data Ingestion

Content Blocks

Custom Attributes

Events

KPIs

Messages

Preference Center

Purchases

Segments

Sends

Sessions

SDK Authentication Keys

Subscription

Templates

Step 2: Install uv

You’ll need to install uv, a tool for dependency management and Python package handling. To install, open your terminal and run the following command:

1

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

1

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

Step 3: Configure your MCP client

Next, configure your MCP client using our pre-provided configuration file.

  1. In Claude Desktop, go to Settings > Developer > Edit Config, then add the following snippet: 
    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"
       }
     }
   }
 }
  2. Save the configuration and restart Claude Desktop.
  3. To verify your connection, try asking a question like “List my Braze campaigns”.
  1. In Cursor, go to Settings > Cursor Settings > MCP Tools > Add Custom MCP, then add the following snippet: 
    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"
       }
     }
   }
 }
  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.

Troubleshooting

Terminal errors

uvx command not found

If you receive an error that uvx command not found, reinstall uv and restart your terminal.

1

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

spawn uvx ENOENT error

If you receive a spawn uvx ENOENT errors, you may need to update the filepath in your client’s config file. First, open your terminal and run the following command:

1

which uvx

The command should return a message similar to the following:

1

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

Copy the message to your clipboard and open your client’s config file. Replace "command": "uvx" with the path you copied, then restart your client. For example:

1

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

Package installation fails

If your package installation fails, try installing a specific Python version instead.

1

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

Client configuration

MCP client can’t find the Braze server

  1. Verify your MCP client configuration syntax is correct.
  2. Restart your MCP client after configuration changes.
  3. Check that uvx is in your system PATH.

Authentication errors

  1. Verify your BRAZE_API_KEY is correct and active.
  2. Ensure your BRAZE_BASE_URL matches your Braze instance.
  3. Check that your API key has the correct permissions.

Connection timeouts or network errors

  1. Verify your BRAZE_BASE_URL is correct for your instance.
  2. Check your network connection and firewall settings.
  3. Ensure you’re using HTTPS in your base URL.

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 [email protected].

Github   Edit this page on GitHub
HOW HELPFUL WAS THIS PAGE?
New Stuff!