Kakao Keyword Ads

카카오 키워드광고(검색광고) 데이터를 조회·분석·리포트 위주로 다루는 MCP 서버. 회사 구성원 여러 명이 하나의 호스팅 서버(GCP Cloud Run)로 연동해 사용하는 것을 목표로 한다. 전체 설계는 DESIGN.md 참고. 라이선스: MIT.

⚠️ 비공식 프로젝트입니다 — 카카오와 무관하며(Not affiliated with Kakao), 카카오 키워드광고 오픈 API를 사용합니다. 사용에는 비즈 앱 전환·비즈니스 인증·API 권한 승인이 필요합니다.

🔐 보안: 자격증명은 .env(gitignore)/Secret Manager에만 두고 커밋하지 마세요. 호스팅 시 /mcp는 기본 개방이라(원격 MCP 클라이언트 호환) 엔드포인트 URL을 공개하지 말고, 다중 사용자 운영 시 Google Workspace OAuth 등으로 접근을 통제하세요. 자세한 건 DEPLOY.md.

자매 프로젝트: KAKAOMomentMCP(카카오모먼트)와 동일한 비즈니스 토큰 인증을 쓴다. 인증 계층(auth.py/config.py/business_auth_api.py/scripts/get_business_token.py)은 사실상 공유하고, 호스트·계층·엔드포인트만 다르다. 검색광고에는 키워드 계층과 품질지수가 추가된다.

현재 상태: 읽기 툴 21종 + 리소스 2종 · Cloud Run 배포 · 라이브 검증 완료

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

• 비즈니스 토큰은 사용자별(로그인한 카카오계정). refresh_token 없음 → 재발급 없이 재사용, 401 시 재발급. 불필요한 재발급은 발급 개수 한도(KOE236) 유발 → 재사용 원칙.
• 접근 가능한 광고계정은 tokeninfo.ad_account_ids가 결정(resource_ids=keyword:* 동의 시 전체 계정).
• 비즈니스 토큰·광고계정 ID는 .env에 저장하지 않는다. 사용자마다 바뀌는 런타임 값이라 툴 호출 시 인자(business_token, ad_account_id)로 전달한다. .env엔 앱 수준 발급 자격증명만 둔다.
• 필요 scope: keyword_management (조회·운영, 생성/삭제 제외).

두 가지 인증 모드 (자매 모먼트 MCP와 동일)

• OAuth 로그인-온-커넥트(호스팅 권장, KAKAO_AUTH_MODE=oauth): 서버가 OAuth 보호 리소스가 되고 IdP는 카카오 비즈니스 인증 — 클라이언트 연결 시 카카오 로그인이 뜨고 각 요청이 토큰을 실어 온다. OAuth 상태는 Firestore에 영속화되어 재배포해도 토큰을 재사용(재발급 없음)한다(KOE236 방지). 자세한 건 DEPLOY.md.
• 세션 로그인(로컬/stdio): login(business_token) → use_account(ad_account_id) → 이후 인자 없이 조회.

호출 흐름 (세션 모드)

1. get_token_info(business_token) → 접근 가능 계정(ad_account_ids) 확인
2. 그중 하나를 ad_account_id로 골라 캠페인/키워드/리포트 조회

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

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

비즈니스 토큰 발급 (사용자 로그인)

.venv/bin/python scripts/get_business_token.py url          # scope 기본값 keyword_management
# → 브라우저 로그인·동의 → code 복사
.venv/bin/python scripts/get_business_token.py exchange --code <AUTH_CODE>
# → 출력된 토큰을 툴 호출 시 business_token 인자로 사용 (.env에 저장하지 않음)

개발 / 실행

uv venv --python 3.13 && uv pip install -e ".[dev]"
.venv/bin/pytest                # 테스트 18종
.venv/bin/kakao-keywordad-mcp   # stdio 서버

툴 (읽기 21종) — 모든 툴 첫 인자 business_token

디스커버리 (토큰만): get_token_info, get_user_info, list_ad_accounts

계정 (+ad_account_id): get_ad_account, get_account_balance, get_biz_right

엔티티: list_campaigns·get_campaign, list_adgroups·get_adgroup, list_keywords·get_keyword·get_keyword_quality(품질지수), list_creatives·get_creative

성과/리포트: get_account_performance, get_campaign_performance, get_adgroup_performance, get_keyword_performance, get_creative_performance, get_performance_report(level=AD_ACCOUNT|CAMPAIGN|AD_GROUP|KEYWORD|CREATIVE) — 공통 인자 start/end(yyyyMMdd) 또는 date_preset, metrics_group

리소스: kakao://metric-glossary, kakao://report-dimensions

호스트 맵

용도	Host
토큰 발급	kauth.kakao.com/oauth/business/{authorize,token}
토큰/사용자 정보	kapi.kakao.com/v1/business/{tokeninfo,userinfo}
광고 API	api.keywordad.kakao.com/openapi/v1 (소재는 /creatives/basic)

선행조건: 비즈니스 앱 전환 + 실명확인 + 키워드광고 권한(keyword_management) 승인 + Redirect URI 등록.

⚠️ 엔드포인트 쿼리 파라미터명·리포트 지표 필드명은 문서 기반 최선 추정. 토큰 확보 후 라이브 검증에서 확정·보정.