Kakao Moment Ads MCP

카카오모먼트 광고 데이터를 조회·분석·리포트 위주로 다루는 읽기 전용 MCP 서버. 회사 구성원 여러 명이 하나의 호스팅 서버(GCP Cloud Run)로 연동해 쓰는 것을 목표로 한다. 전체 설계는 DESIGN.md, 배포는 DEPLOY.md, 향후 과제는 ROADMAP.md 참고. 자매 프로젝트 NaverSearchAds_MCP / kakao-keywordad-mcp(키워드광고)와 아키텍처를 공유한다.

현재 상태

읽기 툴 24종 + 리소스 2종. Cloud Run 배포 + 라이브 검증 완료 (계정/캠페인/광고그룹/소재/리포트 4레벨·다차원 분해까지 실데이터 확인). 읽기 전용(mutating 툴 없음).

인증 모델 — 사용자별 비즈니스 토큰 (중요)

카카오모먼트는 비즈니스 토큰으로 인증하며, 이 토큰은 사용자(로그인한 카카오계정)별이다.

• 전용 플로우 GET /oauth/business/authorize → POST /oauth/business/token. 응답에 refresh_token 없음 → 재발급 없이 재사용하는 장수명 토큰(장기 미사용 시만 만료). 불필요한 재발급은 발급 개수 한도 (KOE236)를 유발하므로 재사용이 원칙.
• 토큰은 token_user_id(사용자)에 귀속되고, 접근 가능한 광고계정은 tokeninfo.ad_account_ids가 결정한다. resource_ids=moment:* 동의 시 사용자 보유 전체 계정 접근.
• 따라서 비즈니스 토큰·광고계정 ID는 .env에 저장하지 않는다. 둘 다 사용자마다 바뀌는 런타임 값.
• .env에는 앱 수준 발급 자격증명만 둔다(아래).

두 가지 인증 모드

모드	용도	동작
OAuth 로그인-온-커넥트 (호스팅 권장)	Cloud Run 다중 사용자	KAKAO_AUTH_MODE=oauth. 서버가 OAuth 보호 리소스가 되고 IdP는 카카오 비즈니스 인증 — 클라이언트 연결 시 카카오 로그인이 뜨고, 각 요청이 카카오 토큰을 실어 온다(구글/네이버 MCP와 동일한 "로그인 베이스"). 별도 로그인 툴 불필요.
세션 로그인 (로컬/stdio)	개인 로컬 사용	login(business_token)으로 토큰을 서버 세션에 저장 → use_account(ad_account_id) → 이후 인자 없이 조회.

두 모드 모두 각 툴에 business_token/ad_account_id를 직접 넘겨 override 가능.

OAuth 상태 영속화 (Firestore) — KOE236 방지

호스팅(OAuth) 모드에서 OAuth 상태(클라이언트 등록·발급 토큰)를 Firestore에 영속화한다 (GCP_PROJECT_ID+KAKAO_OAUTH_FIRESTORE_DATABASE 설정 시). 이로써 재배포해도 기존 비즈니스 토큰을 재사용(재발급 안 함)해 카카오 토큰 발급 개수 한도(KOE236)에 걸리지 않는다. 토큰 정리 시 카카오에도 폐기 요청(/v1/business/revoke)이 나간다. 설정 없으면 파일 저장소로 폴백(로컬 개발용).

설정 (.env — 앱 발급 자격증명만, gitignore됨)

.env.example 복사 후 채운다. 토큰/계정 ID는 여기 넣지 않는다.

KAKAO_REST_API_KEY=...            # OAuth client_id (발급용)
KAKAO_BUSINESS_CLIENT_SECRET=...  # 비즈니스 인증 Client Secret (발급용)
KAKAO_REDIRECT_URI=...            # 앱에 등록한 Redirect URI (발급용)

비즈니스 토큰 발급 (세션 모드용, scripts/get_business_token.py)

.venv/bin/python scripts/get_business_token.py url --scope moment_management
# → 브라우저에서 카카오 로그인·동의 → 리다이렉트 주소의 code= 복사
.venv/bin/python scripts/get_business_token.py exchange --code <AUTH_CODE>
# → 출력된 비즈니스 토큰을 툴 호출 시 business_token 인자로 사용 (.env에 저장하지 않음)

OAuth 로그인-온-커넥트 모드에서는 이 스크립트가 불필요 — 클라이언트 연결 시 카카오 로그인으로 자동 처리.

개발 / 실행

uv venv --python 3.13 && uv pip install -e ".[dev]"
.venv/bin/pytest              # auth / client / tool / route 테스트
.venv/bin/kakao-moment-mcp    # stdio 서버 (.env의 발급 자격증명만 로드)

툴 (읽기 24종)

디스커버리: get_token_info, get_user_info, list_ad_accounts(페이지네이션 전체), session_status, login/logout/use_account

계정: get_ad_account, get_account_balance, list_trackers, list_channel_profiles

엔티티: list_campaigns·get_campaign, list_adgroups·get_adgroup, list_creatives·get_creative

성과/리포트: get_account_performance, get_campaign_performance, get_adgroup_performance, get_creative_performance, get_performance_report(level=AD_ACCOUNT|CAMPAIGN|AD_GROUP|CREATIVE)

타겟/오디언스: list_audiences, list_cohorts · 리소스: kakao://metric-glossary, kakao://report-dimensions

리포트 스펙 (라이브 확정)

• 파라미터명 metricsGroup(단수). 그룹: BASIC/ADDITION/MESSAGE/VIDEO/PIXEL_SDK_CONVERSION(쉼표로 복수).
• 최대 조회 창 31일(초과 시 400 detailCode 60008), 보관 ~2년. 툴은 KAKAO_REPORT_MAX_DAYS로 자동 청킹.
• 하위 레벨(campaign/adGroup/creative)은 대상 ID를 반복 파라미터로 전달하며 개수 한도가 낮다(≈5) → 툴이 KAKAO_REPORT_MAX_IDS(기본 5)로 ID를 배치 청킹(초과 시 detailCode 78003 방지).
• dimension: AGE_BAND/GENDER/DEVICE_TYPE/PLACEMENT/CREATIVE_FORMAT/LOCATION/HOUR.
• 비용 필드는 cost(키워드광고는 spending). 메시지 광고는 발송당 과금 → 노출 0인데 비용만 잡히므로 디스플레이 성과와 분리 해석 필요.

호스트 맵

용도	Host
토큰 발급	kauth.kakao.com/oauth/business/{authorize,token}
토큰/사용자 정보·폐기	kapi.kakao.com/v1/business/{tokeninfo,userinfo,revoke}
광고 API	apis.moment.kakao.com/openapi/v4

선행조건: 비즈니스 앱 전환 + 실명확인 + 카카오모먼트 권한(moment_management) 승인 + Redirect URI 등록.

라이선스

MIT — LICENSE.