# Kakao Keyword Ads MCP (카카오 키워드광고 / 검색광고)

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

> ⚠️ **비공식 프로젝트**입니다 — 카카오와 무관하며(Not affiliated with Kakao), 카카오 키워드광고
> 오픈 API를 사용합니다. 사용에는 비즈 앱 전환·비즈니스 인증·API 권한 승인이 필요합니다.
>
> 🔐 **보안**: 자격증명은 `.env`(gitignore)/Secret Manager에만 두고 커밋하지 마세요. 호스팅 시
> `/mcp`는 기본 개방이라(원격 MCP 클라이언트 호환) **엔드포인트 URL을 공개하지 말고**, 다중 사용자
> 운영 시 Google Workspace OAuth 등으로 접근을 통제하세요. 자세한 건 [DEPLOY.md](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](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 (발급용)
```

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

```bash
.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에 저장하지 않음)
```

## 개발 / 실행

```bash
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 등록.
>
> ⚠️ 엔드포인트 쿼리 파라미터명·리포트 지표 필드명은 문서 기반 최선 추정. 토큰 확보 후 **라이브 검증에서 확정·보정**.