Skip to content

Setting up the Braze MCP server

Learn how to set up the 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 the Braze MCP server

Step 1: Install uv

First, install uv—a command-line tool by Astral for dependency management and Python package handling.

Open your terminal application, paste the following command, then press Enter.

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

The output will be similar to the following:

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!

Open Windows PowerShell, paste the following command, then press Enter.

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

The output will be similar to the following:

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!

Step 2: Create an API key

Braze MCP server supports 38 read-only endpoints that do not return data from Braze user profiles. 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 3: Get your identifer and endpoint

When you configure your MCP client, you’ll need your API key’s identifier and your workspace’s REST endpoint. To get these details, go back to the API Keys page in the dashboard—keep this page open, so you can reference it during the next step.

The 'API Keys' in Braze showing a newly created API key and the user's REST endpoint.

Step 4: Configure your MCP client

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

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": "key-identifier",
        "BRAZE_BASE_URL": "rest-endpoint"
      }
    }
  }
}

Replace key-identifier and rest-endpoint with the corresponding values from the API Keys page in Braze. Your configuration should be similar to the following:

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

When you’re finished, save the configuration and restart Claude Desktop.

In Cursor, go to Settings > Tools and Integrations > 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"
      }
    }
  }
}

Replace key-identifier and rest-endpoint with the corresponding values from the API Keys page in Braze. Your configuration should be similar to the following:

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

When you’re finished, save the configuration and restart Cursor.

Step 5: Send a test prompt

Now that you’ve set up the Braze MCP server, try sending a test prompt to your MCP client. For other examples and best practices, see Using the Braze MCP server.

'What are my available Braze functions?' being asked and answered in Claude.

'What are my available Braze functions' being asked and answered in Cursor.

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

HOW HELPFUL WAS THIS PAGE?
New Stuff!