Skip to content

Braze MCP 서버 설정하기

Claude 및 Cursor와 같은 자연어 도구를 사용하여 Braze 데이터와 상호작용할 수 있도록 Braze MCP 서버를 설정하는 방법을 알아보세요. 더 일반적인 정보는 Braze MCP 서버를 참조하세요.

필수 조건

시작하기 전에 다음이 필요합니다:

Braze MCP 서버 설정하기

1단계: uv 설치하기

먼저 uv—의존성 관리 및 Python 패키지 처리를 위한 Astral의 명령줄 도구를 설치하세요.

터미널 애플리케이션을 열고, 다음 명령을 붙여넣은 후 Enter를 누르세요.

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!

Windows PowerShell을 열고, 다음 명령을 붙여넣은 후 Enter를 누르세요.

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!

2단계: API 키 생성

Braze MCP 서버는 Braze 고객 프로필에서 데이터를 반환하지 않는 39개의 엔드포인트를 지원합니다.

API 키를 생성하려면:

  1. 설정 > API 키 > API 키로 이동합니다.
  2. 새 키를 생성합니다.
  3. 키에 다음 권한 중 일부 또는 전부를 할당합니다.
지원되는 권한 목록

Campaigns

Canvas

Catalogs

Cloud Data Ingestion

Content Blocks

Custom Attributes

Events

KPIs

Media Library

이 엔드포인트는 Braze MCP 서버에서 지원하는 쓰기 엔드포인트입니다. 에이전트가 미디어 라이브러리에 자산을 업로드하도록 하려는 경우에만 이 권한을 추가하세요.

Messages

Preference Center

Purchases

Segments

Sends

Sessions

SDK Authentication Keys

Subscription

Templates

3단계: 식별자 및 엔드포인트 가져오기

MCP 클라이언트를 구성할 때 API 키의 식별자와 워크스페이스의 REST 엔드포인트가 필요합니다. 이 세부 정보를 확인하려면 대시보드의 API 키 페이지로 돌아가세요—다음 단계에서 참조할 수 있도록 이 페이지를 열어 두세요.

Braze의 API 키 페이지에서 새로 생성된 API 키와 사용자의 REST 엔드포인트를 보여줍니다.

4단계: MCP 클라이언트 구성

미리 제공된 구성 파일을 사용하여 MCP 클라이언트를 구성하세요.

Claude Desktop 커넥터 디렉토리를 사용하여 MCP 서버를 설정하세요.

  1. Claude Desktop에서 Settings > Connectors > Browse Connectors > Desktop Extensions > Braze MCP Server > Install로 이동합니다.
  2. API 키와 기본 URL을 입력합니다.
  3. 구성을 저장하고 Claude Desktop을 재시작합니다.

Cursor에서 Settings > Tools and Integrations > MCP Tools > Add Custom MCP로 이동한 다음 다음 스니펫을 추가하세요:

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

key-identifier와 rest-endpoint를 Braze의 API 키 페이지에서 해당 값으로 교체하세요. 구성은 다음과 유사해야 합니다:

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

완료되면 구성을 저장하고 Cursor를 재시작하세요.

Gemini CLI는 ~/.gemini/settings.json에서 사용자 설정을 읽습니다. 이 파일이 존재하지 않으면 터미널에서 다음을 실행하여 생성할 수 있습니다:

1
2

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

다음으로, 터미널 프롬프트에서 @BZXXXXXXXX 앞의 정확한 문자열로 yourname을 교체하세요. 그런 다음 Braze의 API 키 페이지에서 해당 값으로 key-identifier와 rest-endpoint를 교체하세요.

구성은 다음과 유사해야 합니다:

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

완료되면 구성을 저장하고 Gemini CLI를 재시작하세요. 그런 다음 Gemini에서 다음 명령을 실행하여 Braze MCP 서버가 나열되어 있고 도구와 스키마를 사용할 수 있는지 확인하세요:

1
2
3
4

gemini
/mcp
/mcp desc
/mcp schema

사용 가능한 도구와 스키마가 있는 braze 서버가 나열되어야 합니다.

5단계: 테스트 프롬프트 보내기

Braze MCP 서버를 설정한 후 MCP 클라이언트에 테스트 프롬프트를 보내보세요. 다른 예제 및 모범 사례는 Braze MCP 서버 사용하기를 참조하세요.

Claude에서 사용 가능한 Braze 기능이 무엇인지 질문하고 답변을 받는 모습입니다.

Cursor에서 사용 가능한 Braze 기능이 무엇인지 질문하고 답변을 받는 모습입니다.

Gemini CLI에서 사용 가능한 Braze 기능이 무엇인지 질문하고 답변을 받는 모습입니다.

문제 해결

터미널 오류

uvx 명령을 찾을 수 없음

uvx 명령을 찾을 수 없다는 오류가 발생하면 uv를 재설치하고 터미널을 재시작하세요.

1

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

spawn uvx ENOENT 오류

spawn uvx ENOENT 오류가 발생하면 클라이언트의 구성 파일에서 파일 경로를 업데이트해야 할 수 있습니다. 먼저 터미널을 열고 다음 명령을 실행하세요:

1

which uvx

명령은 다음과 유사한 메시지를 반환해야 합니다:

1

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

메시지를 클립보드에 복사하고 클라이언트의 구성 파일을 여세요. "command": "uvx"를 복사한 경로로 교체한 후 클라이언트를 재시작하세요. 예를 들어:

1

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

패키지 설치 실패

패키지 설치가 실패하면 특정 Python 버전을 대신 설치해 보세요.

1

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

클라이언트 구성

MCP 클라이언트가 Braze 서버를 찾을 수 없음

  1. MCP 클라이언트 구성 구문이 올바른지 확인하세요.
  2. 구성 변경 후 MCP 클라이언트를 재시작하세요.
  3. uvx가 시스템 PATH에 있는지 확인하세요.

인증 오류

  1. BRAZE_API_KEY가 올바르고 활성 상태인지 확인하세요.
  2. BRAZE_BASE_URL이 Braze 인스턴스와 일치하는지 확인하세요.
  3. API 키에 올바른 권한이 있는지 확인하세요.

연결 시간 초과 또는 네트워크 오류

  1. BRAZE_BASE_URL이 인스턴스에 대해 올바른지 확인하세요.
  2. 네트워크 연결 및 방화벽 설정을 확인하세요.
  3. 기본 URL에서 HTTPS를 사용하고 있는지 확인하세요.

Disclaimer

모델 컨텍스트 프로토콜(MCP)은 새로 도입된 오픈 소스 프로토콜로, 현재 보안 문제나 취약점에 노출될 수 있습니다.

Braze MCP 서버 설정 코드 및 지침은 Braze에서 “있는 그대로” 어떠한 보증 없이 제공되며, 고객은 자신의 위험 부담 하에 사용합니다. Braze는 부적절한 설정, MCP의 오용 또는 발생할 수 있는 잠재적인 보안 문제로 인한 모든 결과에 대해 책임을 지지 않습니다. Braze는 고객이 구성을 신중하게 검토하고, Braze 환경의 무결성 및 보안과 관련된 위험을 줄이기 위해 안내된 지침을 따를 것을 강력히 권장합니다.

도움이나 추가 설명이 필요하시면 Braze 고객지원으로 문의해 주세요.
New Stuff!