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.

• macos and linux
• windows

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

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!

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

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.

Step 3: Get your identifier 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.

Step 4: Configure your MCP client

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

• claude
• cursor
• gemini cli

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

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

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

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

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

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

1
2
3
4
gemini
/mcp
/mcp desc
/mcp schema

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.

• claude
• cursor
• gemini cli

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