Skip to main content
Glama
kakao-moment-mcp

kakao-moment-mcp

by PlatAid

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 다중 사용자

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.

Available Tools

24 tools
get_account_balanceB
Read-only

광고계정 실시간 잔액 (GET /adAccounts/balance).

Inputs: ad_account_id, business_token. Returns: object

get_account_performanceB
Read-only

광고계정 성과 리포트 (GET /adAccounts/report). ID 불필요.

Inputs: end, start, dimension, time_unit, +4 more. Returns: result

get_ad_accountB
Read-only

광고계정 상세 (GET /adAccounts/{adAccountId}).

Inputs: ad_account_id, business_token. Returns: object

get_adgroupB
Read-only

단일 광고그룹 상세 (GET /adGroups/{id}).

Inputs: adgroup_id (required), ad_account_id, business_token. Returns: object

get_adgroup_performanceB
Read-only

광고그룹별 성과 리포트 (GET /adGroups/report). adGroupId 필수 — 미지정 시 (선택적 campaign_id 범위의) 광고그룹을 자동 열거.

Inputs: end, start, dimension, time_unit, +6 more. Returns: result

get_campaignA
Read-only

단일 캠페인 상세 (GET /campaigns/{id}).

Inputs: campaign_id (required), ad_account_id, business_token. Returns: object

get_campaign_performanceA
Read-only

캠페인별 성과 리포트 (GET /campaigns/report). campaignId 필수 — 미지정 시 계정의 전체 캠페인을 자동 열거해 조회한다.

Inputs: end, start, dimension, time_unit, +5 more. Returns: result

get_creativeB
Read-only

단일 소재 상세 (GET /creatives/{id}).

Inputs: creative_id (required), ad_account_id, business_token. Returns: object

get_creative_performanceA
Read-only

소재별 성과 리포트 (GET /creatives/report). creativeId 필수 — 미지정 시 (선택적 adgroup_id 범위의) 소재를 자동 열거.

Inputs: end, start, dimension, time_unit, +6 more. Returns: result

get_performance_reportB
Read-only

레벨 지정 통합 성과 리포트. 인사이트 도출용 1급 툴. 하위 레벨은 계정 내 전체 엔티티를 자동 열거.

Inputs: level (required), end, start, dimension, +5 more. Returns: result

get_token_infoB
Read-only

비즈니스 토큰의 소유자(token_user_id)·접근 가능 광고계정 (GET kapi.kakao.com/v1/business/tokeninfo).

Inputs: business_token. Returns: object

get_user_infoC
Read-only

비즈니스 토큰 사용자 정보 (GET /v1/business/userinfo).

Inputs: business_token. Returns: object

list_ad_accountsA
Read-only

토큰이 접근 가능한 광고계정 전체 목록 (GET /adAccounts/pages, 전 페이지 순회).

Inputs: business_token. Returns: result

list_adgroupsC
Read-only

광고그룹 목록 (GET /adGroups).

Inputs: campaign_id, ad_account_id, business_token. Returns: result

list_audiencesB
Read-only

오디언스 목록 (GET /targetings/audiences).

Inputs: ad_account_id, business_token. Returns: result

list_campaignsB
Read-only

캠페인 목록 (GET /campaigns).

Inputs: ad_account_id, campaign_type, business_token. Returns: result

list_channel_profilesB
Read-only

카카오톡 채널 프로필 목록 (GET /adAccounts/channel/profiles).

Inputs: ad_account_id, business_token. Returns: result

list_cohortsC
Read-only

광고반응타겟(cohort) 목록 (GET /targetings/cohort/list).

Inputs: ad_account_id, business_token. Returns: result

list_creativesC
Read-only

소재 목록 (GET /creatives).

Inputs: adgroup_id, ad_account_id, business_token. Returns: result

list_trackersA
Read-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_statusA
Read-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

    B3.4/5.0

    Scored across 24 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Read-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.
      18
      MIT
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      A 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.
      -
    • F
      license
      Not graded
      quality
      B
      maintenance
      MCP 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.
      -