kakao-moment-mcp
Provides tools to read, analyze, and report on Kakao Moment ads data, including campaigns, ad groups, creatives, and performance reports.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kakao-moment-mcp show performance report for last 30 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 툴 없음).
Related MCP server: flin-meta-ads-mcp
인증 모델 — 사용자별 비즈니스 토큰 (중요)
카카오모먼트는 비즈니스 토큰으로 인증하며, 이 토큰은 사용자(로그인한 카카오계정)별이다.
전용 플로우
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 다중 사용자 |
|
세션 로그인 (로컬/stdio) | 개인 로컬 사용 |
|
두 모드 모두 각 툴에 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 |
토큰 발급 |
|
토큰/사용자 정보·폐기 |
|
광고 API |
|
선행조건: 비즈니스 앱 전환 + 실명확인 + 카카오모먼트 권한(
moment_management) 승인 + Redirect URI 등록.
라이선스
MIT — LICENSE.
Available Tools
24 toolsget_account_balanceBRead-only
광고계정 실시간 잔액 (GET /adAccounts/balance).
Inputs: ad_account_id, business_token. Returns: object
get_account_performanceBRead-only
광고계정 성과 리포트 (GET /adAccounts/report). ID 불필요.
Inputs: end, start, dimension, time_unit, +4 more. Returns: result
get_ad_accountBRead-only
광고계정 상세 (GET /adAccounts/{adAccountId}).
Inputs: ad_account_id, business_token. Returns: object
get_adgroupBRead-only
단일 광고그룹 상세 (GET /adGroups/{id}).
Inputs: adgroup_id (required), ad_account_id, business_token. Returns: object
get_adgroup_performanceBRead-only
광고그룹별 성과 리포트 (GET /adGroups/report). adGroupId 필수 — 미지정 시 (선택적 campaign_id 범위의) 광고그룹을 자동 열거.
Inputs: end, start, dimension, time_unit, +6 more. Returns: result
get_campaignARead-only
단일 캠페인 상세 (GET /campaigns/{id}).
Inputs: campaign_id (required), ad_account_id, business_token. Returns: object
get_campaign_performanceARead-only
캠페인별 성과 리포트 (GET /campaigns/report). campaignId 필수 — 미지정 시 계정의 전체 캠페인을 자동 열거해 조회한다.
Inputs: end, start, dimension, time_unit, +5 more. Returns: result
get_creativeBRead-only
단일 소재 상세 (GET /creatives/{id}).
Inputs: creative_id (required), ad_account_id, business_token. Returns: object
get_creative_performanceARead-only
소재별 성과 리포트 (GET /creatives/report). creativeId 필수 — 미지정 시 (선택적 adgroup_id 범위의) 소재를 자동 열거.
Inputs: end, start, dimension, time_unit, +6 more. Returns: result
get_performance_reportBRead-only
레벨 지정 통합 성과 리포트. 인사이트 도출용 1급 툴. 하위 레벨은 계정 내 전체 엔티티를 자동 열거.
Inputs: level (required), end, start, dimension, +5 more. Returns: result
get_token_infoBRead-only
비즈니스 토큰의 소유자(token_user_id)·접근 가능 광고계정 (GET kapi.kakao.com/v1/business/tokeninfo).
Inputs: business_token. Returns: object
get_user_infoCRead-only
비즈니스 토큰 사용자 정보 (GET /v1/business/userinfo).
Inputs: business_token. Returns: object
list_ad_accountsARead-only
토큰이 접근 가능한 광고계정 전체 목록 (GET /adAccounts/pages, 전 페이지 순회).
Inputs: business_token. Returns: result
list_adgroupsCRead-only
광고그룹 목록 (GET /adGroups).
Inputs: campaign_id, ad_account_id, business_token. Returns: result
list_audiencesBRead-only
오디언스 목록 (GET /targetings/audiences).
Inputs: ad_account_id, business_token. Returns: result
list_campaignsBRead-only
캠페인 목록 (GET /campaigns).
Inputs: ad_account_id, campaign_type, business_token. Returns: result
list_channel_profilesBRead-only
카카오톡 채널 프로필 목록 (GET /adAccounts/channel/profiles).
Inputs: ad_account_id, business_token. Returns: result
list_cohortsCRead-only
광고반응타겟(cohort) 목록 (GET /targetings/cohort/list).
Inputs: ad_account_id, business_token. Returns: result
list_creativesCRead-only
소재 목록 (GET /creatives).
Inputs: adgroup_id, ad_account_id, business_token. Returns: result
list_trackersARead-only
픽셀 & SDK(트래커) 목록 (GET /adAccounts/trackers).
Inputs: ad_account_id, business_token. Returns: result
loginA
비즈니스 토큰으로 로그인 — tokeninfo 검증 후 서버 세션에 저장. 이후 툴은 토큰 인자 없이 호출.
Inputs: business_token (required). Returns: object
logoutA
세션의 로그인/계정 정보를 지운다.
Inputs: no named parameters. Returns: object
session_statusARead-only
현재 인증 상태(로그인 여부·token_user_id·선택된 계정). 토큰 값은 노출 안 함.
OAuth 로그인-온-커넥트 모드면 요청의 OAuth 토큰 컨텍스트를 보고(=실제 인증 경로), 아니면 세션 저장소(login 툴/웹 로그인)를 본다.
Inputs: no named parameters. Returns: object
use_accountA
이후 조회의 기본 대상 광고계정을 세션에 설정.
Inputs: ad_account_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Most tools are distinct, but the performance report family overlaps: get_account_performance, get_campaign_performance, get_adgroup_performance, get_creative_performance can all be subsumed by get_performance_report, which also auto-enumerates entities. Additionally, session_status and get_token_info both expose token_user_id, creating some ambiguity.
The naming is largely consistent with verb_noun (list_*, get_*, use_account). Notable deviations include get_performance_report (which inverts the entity-first pattern) and login/logout/use_account as standalone verbs, but these are natural exceptions and do not cause confusion.
At 24 tools, this is slightly above the typical well-scoped range, but the coverage is broad across authentication, account management, campaign/adgroup/creative reads, and performance reports. The redundancy of get_performance_report with the level-specific performance tools slightly inflates the count but overall each tool has a legitimate use.
The tool set covers the full read/query lifecycle for campaigns, adgroups, creatives, and accounts, plus performance reporting at multiple levels. Missing are create/update/delete operations and get-single for audiences/cohorts/trackers, but the server appears designed as an insights/reporting tool, so these are acceptable minor gaps.
Maintenance
Related MCP Connectors
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Hosted MCP server for Google Ads and LinkedIn Ads analysis.
Hosted MCP server for GA4, Google Ads and Search Console. Google OAuth, nothing to install.
Google Ads MCP server — manage campaigns, keywords, and metrics.
Related MCP Servers
- AlicenseBqualityDmaintenanceRead-only MCP server for querying Shopify analytics data, including orders, customers, products, sales, retention, and attribution.19MIT
- AlicenseBqualityBmaintenanceRead-only MCP server for Meta Ads that lists and reads ad accounts, campaigns, ad sets, ads, ad images, creatives, and fetches insights at various levels.18MIT
- -licenseNot gradedqualityNot gradedmaintenanceA private, read-only MCP server that enables retrieval and analysis of Google Ads reporting data (campaigns, ad groups, keywords, search terms, cost, conversions) from authorized accounts through a locally operated server.-
- FlicenseNot gradedqualityBmaintenanceMCP server for the Meta Marketing API enabling ad performance reports and operational adjustments like pause/resume and budget changes on client ad accounts, with strict allowlist and read-only safeguards.-