솔루션 가이드

관심

AI 분석 자동화 Mixpanel Headless 설치부터 자동화까지 실무 완벽 가이드

2026-08-26

by.

Nicky(강보라)

Example H2

Example H3

함께 보면 좋은 글, Mixpanel AI Headless 시리즈

1편. Mixpanel MCP, 자연어로 데이터에 묻기
‍2편. Mixpanel Headless, 코드로 믹스패널 데이터 추출해 분석 자동화하기
‍3편. Headless 설치부터 첫 자동화까지 완벽실무 가이드
4편. Mixpanel Headless 설치 후, 데이터 확인 사례

1편 글에서 Headless가 어떤 도구인지, 우리 팀에 필요한지를 다뤘고,
이번에는 실제로 설치해서 첫 결과를 받아보는 과정을 소개합니다.

설치 자체는 명령어 두 줄이면 되지만 직접 세팅해 보니 명령어가 아니라 인증과 권한 쪽에서 시간이 많이 걸렸습니다. 그래서 이 글은 어떤 순간에 어떻게 인증하고 무엇을 선택해야하는지를 정리해봤으니 주목하세요 :)

터미널에서 pip install를 실행해 Headless를 설치하는 모습

Headless 설치 전 체크리스트 3가지

Python 3.10 이상. 터미널에서 python --version으로 확인합니다.
Mixpanel 계정 또는 Service Account.
프로젝트의 데이터 리전. us, eu, in 중 하나입니다만 리전이 틀리면 인증이 실패합니다. 국내 고객사는 대부분 us인데, 계약 시점이나 조건에 따라 eu인 경우도 있습니다. Mixpanel 프로젝트 설정에서 확인하거나, 모르면 도입을 담당한 파트너에게 물어보세요.

1단계. 설치

터미널이나 Claude Code에 아래 코드를 붙입니다.

pip install mixpanel-headless

설치가 됐는지는 이렇게 확인합니다. 결과로 버전 번호가 찍히면 성공이에요.

mp --version

터미널이익숙하지 않다면 Claude Code 같은 코딩 에이전트에게 "mixpanel-headless 설치해줘"라고 요청하세요. 다만 설치가 실패했을 때 원인을 읽어야 하는 건 결국 사람이라, 첫 설치만큼은 직접 해보시길 권장합니다.

2단계. 인증 - 가장 많이 막히는 부분!

인증 방식은 1) 내 개인 계정 또는 2) Service Account을 쓸 수도 있어요.

무슨 차이일까요? 내 노트북에 내 계정으로 Headless를 수행할떄는 브라우저가 열리고 내가 액세스를 승인합니다. 하지만 서버가 매주 월요일 밤 12시에 알아서 데이터를 업데이트 할떄는 승인해 줄 사람이 없죠. 이때 쓰는 게 Service Account입니다. Mixpanel에서 Service Account를 발급받고 ID와 PW 계정 정보를 서버에 넣어두면 브라우저 없이 인증 됩니다.

둘 다 설정하는 것도 가능해요. 하지만.같은 터미널에서 동시에 쓸 수는 없고, 둘다 실행하면서비스 어카운트가 우선 수행되요.

실무에서 추천 드리는 방식

탐색과 개발 - 개인 계정(mp login). 내가 보는 것과 코드가 보는 게 같아서 디버깅이 쉽습니다
서버 자동화 - 서비스 계정 환경변수. 그 서버에만 설정합니다

[옵션1] 내 계정에서 인증하기

내 계정으로 Headless 로 믹스패널에 접속하기 위해 터미널에 아래 명령어를 치세요.

mp login

⚠️ 내 계정 인증은 터미널에서만 가동합니다. Headless 설치는 코딩 에이전트에게 시킬 수 있지만, mp login은 안 됩니다. 브라우저를 띄우고 사용자가 승인하기를 기다리는 방식이라, 터미널에서 직접 입력하셔야 해요. 에이전트에게 요청하면 "직접 실행해 주세요"라고 답이 반환됩니다.

브라우저가 열리고, Mixpanel 계정으로 로그인하면 접근 가능한 프로젝트 목록이 뜹니다. 접속을 원하는 프로젝트의 번호를 고르면 기본 프로젝트로 지정되요.

프로젝트가 많거나 연결 프로젝트로 바꾸려면 목록 번호 대신 ID로 직접 지정할 수 있어요.

mp project use 123456

토큰은 로컬에 저장되고 만료되면 알아서 갱신돼요. 처음 써보는 단계에서는 이 방식이 가장 간단합니다.

[옵션2] Service Account로 인증하기

서버에서 자동으로 돌릴 때는 Service Account를 사용해요. mp login은 브라우저를 열고 승인을 기다리는데, 새벽에 혼자 도는 서버에는 눌러줄 사람이 없으니까요.

계정 정보를 기입하기 위해 환경변수 네 개를 설정합니다.

환경변수는 컴퓨터에 이름표를 붙여 값을 저장해 두는 방식이에요. 비밀번호를 PASSWORD라는 코드로 넣는 방식이라 파일을 공유하거나 저장소에 올려도 값이 노출되지 않아요

export MP_USERNAME="발급받은 서비스 계정 ID"
export MP_SECRET="시크릿"    
export MP_PROJECT_ID="프로젝트 ID"
export MP_REGION="us"

‍

Account 발급 권한은 Mixpanel 프로젝트 오너에게 있어요. 자동화를 만들려는 사람이 마케터나 PM인 경우, 본인 권한으로는 발급이 안 됩니다.

서비스 어카운트가 없다면 Owner에게 요청하세요

요청 예시 - 믹스패널 코호트를 내부 CRM툴로 전송하기 위해, 읽기/코호트 생성 권한으로 서비스 어카운트를 생성해 User name과 Secret 전달 요청 드립니다.

어떤 프로젝트에, 어떤 범위의 권한이 필요한지 정리‍
- Mixpanel 권한은 크게, 읽기만/대시보드나 코호트 생성/프로젝트 설정까지 3개로 나뉩니다. 자동화 용도라면 대부분 읽기, 대시보드 생성으로 충분합니다.

프로젝트 오너에게 발급 요청
- 오너가 데이터에 접근할 수 있는 Service Account를 생성합니다. 아래와 같은 접속 정보 Username과 Secret를 받아 서비스 어카운트를 사용하게 됩니다.

시크릿을 안전하게 전달받아 환경변수로 설정
- 시크릿은 생성 직후 한 번만 보입니다. 창을 닫으면 다시 볼 수 없어서 새로 만들어야 해요. 오너가 발급하고 나에게 전달했다면 받은 뒤에는 원본 메시지를 삭제하세요.

[3] 연결이 됐는지 확인합니다

mp account test

ok가 true면 인증 통과, account_name은 지금 쓰고 있는 계정, accessible_project_count는 이 계정으로 접근 가능한 프로젝트 개수예요.

accessible_project_count에 노출되는 접근 가능 프로젝트 개수를 꼭 확인하세요. 인증은 됐는데 이 값이 0이면 계정에 권한이 안 붙은 상태라, 쿼리를 돌려도 빈 결과만 나오게 됩니다.

잠깐! 계정 이름 변경하기

연결되었다고 나온 계정이 우리 프로젝트 이름과 다르다고 놀라지 마세요!

‍mp login은 조직 이름에서 계정 이름을 자동으로 만드므로, car-pet-2와 같이 이상한 이름이 나온다면 아래와 같이 변경하시면 됩니다.

 mp login --name mfl

‍

3단계. 프로젝트 이벤트 목록 확인하기

바로 쿼리를 짜고 싶으시겠지만, 이벤트부터 체크하세요. 앞 글에서 말씀드린 것처럼 이벤트가 엉망이면 자동화가 조용히 틀리거든요.

[옵션1] 현재 프로젝트 수집 이벤트 - 렉시콘 확인

⚠️ 참고로 이 작업은 터미널보다 Mixpanel 화면 작업을 권장 드립니다. Lexicon에 들어가면 이벤트와 속성이 표로 정리돼 있고, 발생량과 마지막 수집 시각을 나란히 볼 수 있어요.

Tidy Up AI를 활용하거나 같은 행동이 여러 이름으로 흩어져 있는지, 정의만 남고 값이 안 들어오는 이벤트가 있는지 검토하세요.

텍소노미 검증에 대한 질문이 있다면 알려주세요
📩 solutions@mfitlab.com / nicky@mfitlab.com

[옵션2] 현재 프로젝트 수집 이벤트 - 터미널 확인

터미널에서 확인하고 싶다면 이 명령어를 사용하세요. 자동화 코드가 참조할 이름을 스크립트로 검증하거나, 여러 프로젝트를 한꺼번에 훑을 때 유용해요.

제가 고객사 진단에서 가장 자주 발견하는 지점도 이 곳인데요. 문서상으로는 정의돼 있는데 실제로는 값이 안 들어오는 속성, 반대로 정의된 적 없는데 계속 쌓이고 있는 이벤트가 나오거든요. 자동화 코드는 이 목록에 있는 이름만 참조해야 합니다.

mp inspect events # 믹스패널 수집 이벤트 목록 확인
mp inspect top-events # 믹스패널 상위 수집량 이벤트 확인

실제로 어느 것이 쓰이고 있는지는 최근 발생량을 확인해보고, 특정 이벤트에 어떤 속성이 수집되며, 그 속성에 실제로 어떤 값이 들어오는지도 확인할 수 있어요.

mp inspect properties --event Purchase   # 이 이벤트에 어떤 속성이 붙어 있는지
mp inspect values --event Purchase --property country   # 그 속성에 실제로 들어온 값 확인

‍

4단계. 첫 결과 받아보기

앞에서 이벤트 목록을 확인했으니, 터미널 명령을 사용해 실제 믹스패널 데이터를 뽑아보겠습니다.

mp inspect funnels #프로젝트에 저장된 퍼널 목록 보기

ID는 퍼널마다 붙는 고유 ID예요. 데이터 조회할 때 퍼널 이름 대신 이 번호를 씁니다.

이제 퍼널 리포트 ID값으로 데이터를 조회해볼게요.

mp query funnel 89656169 
  --from 2026-07-01 
  --to 2026-07-31 
  --format table

산정한 결과 값을 확인합니다.

여기까지가 코드 없이 할 수 있는 범위입니다. 실제로 팀에 따라서는 이 정도만으로도 충분해요. 매주 같은 명령을 치는 것보다는 낫고, 화면을 열지 않아도 숫자를 확인할 수 있으니까요.

5단계. 조회한 데이터 다른 툴로 보내기 = Python

터미널에 출력된 믹스패널 데이터를 슬랙에 보내거나, 사내 주문 데이터와 합치거나, 30% 아래로 떨어졌을 때만 알림을 보내려면 전송코드를 작성해야 하는데요. 이때 쓰는 코드가 Python입니다.

[1] Python 코드 작성하기

파이썬 코드 작성은 코딩 에이전트에게 시키면 되세요. Claude Code에 "지난달 가입에서 구매까지 퍼널 뽑는 스크립트 만들어줘"라고 요청하면 코드를 쓰고, 파일로 저장하고, 실행해서 결과까지 확인해줍니다. 앞 단계에서 확인한 이벤트 이름만 정확히 알려주시면 되요!

만들어지는 코드는 이런 형태예요.

import mixpanel_headless as mp

ws = mp.Workspace()
result = ws.query_funnel(["Signup", "Purchase"], conversion_window=7, last=90)

print(result.df)
print(f"전환율: {result.overall_conversion_rate:.1%}")

이 코드 중에 마지막 줄의 print 뒷부분의 두 줄 result.df만 기억하시면 되세요.

result.df는 화면에 출력된 숫자를 표 형태로 담아 프로그램이 꺼내 쓸 수 있습니다.

그래서 "전환율이 5% 아래면 알림 보내"라거나 "이 표를 사내 매출 데이터와 합쳐"라는 동작이 가능해져요. 터미널에서는 안 되던 것들이지요.

리텐션도 같은 방식입니다. Mixpanel 화면에서 만들 수 있는 이벤트 집계, 퍼널, 리텐션, 사용자 여정, 사용자 프로필 조회까지 모두 가져올 수 있어요. 대시보드나 코호트, 피처 플래그를 만들고 수정하는 것도 코딩 에이전트에게 코드를 요청하시면 되요.

6단계. 자동화하기

이제 나머지는 일반적인 Python 작업이예요. 만든 파일을 스케줄러에 걸면 정해진 시간에 알아서 돌 눅버라면 cron, 사내 워크플로 도구가 있다면 거기에 등록하세요.

단, 어떤 이름의 파일이 어디에 저장됐는지는 확인해 두세요. 나중에 이 스크립트를 매주 자동으로 돌리려면 그 위치가 필요하고, 결과가 이상할 때 열어봐야 합니다.

파일 경로를 잃어버렸다면?
클로드코드에게 "방금 만든 파일 어디에 저장했어?"라고 물어보세요

이 단계도 코딩 에이전트에게 맡기는 편이 빨라요. "이 스크립트 결과를 슬랙 채널에 표로 보내줘", "매주 월요일 아침 9시에 돌게 해줘"처럼 말로 설명하면 나머지를 채워줘요.

⚠️ 잠깐! 얼리액세스를 신청하세요.
현재 시간당 60회 리밋입니다. 운영에 사용하실 거라면 얼리액세스를 신청하세요.
탐색 단계에서는 넉넉하지만, 여러 프로젝트를 순회하거나 세분화된 조건으로 반복 조회하면 금방 닿습니다. 운영 규모로 쓰실 거라면 Mixpanel에 얼리 액세스를 신청해 한도를 높여야 합니다.