kakao-moment-mcp 0.1.1

Kakao Moment 광고 운영 자동화 MCP 서버 - Claude Desktop에서 자연어로 카카오모먼트 광고 조회/리포트

Kakao Moment MCP

Claude Desktop 같은 AI 에이전트에서 자연어로 카카오모먼트 광고를 운영할 수 있게 해주는 MCP (Model Context Protocol) 서버입니다.

"어제 캠페인별 성과 요약해줘", "오늘 일예산 얼마나 썼어?", "최근 7일 ROAS 가장 좋은 광고그룹 5개" ← 이런 요청을 Claude 에게 그대로 던지면 됩니다.

---

✨ 무엇을 할 수 있나요? (v0.1 — Phase 1: 조회/리포트 7개 도구)

도구	설명
get_ad_account_info	광고계정 정보, 상태
get_bizmoney	비즈머니 잔액
list_campaigns	캠페인 목록 + 상태 + 일예산
list_adgroups	광고그룹 목록 + 상태 + 입찰가 + 일예산
list_creatives	소재 목록 + 상태
get_performance_report	기간/단위별 성과 (노출·클릭·비용·전환·CTR·CPC·ROAS)
get_today_status	오늘 일예산 소진율, 페이스, 잔여

🚧 Phase 2 (ON/OFF 제어), Phase 3 (예산/입찰 조정), Phase 4 (소재 관리) 도구는 안정성 검증 후 점진 추가됩니다. Write 도구는 항상 dry_run 옵션과 변경 상한선이 적용됩니다.

---

🔐 보안 원칙 (반드시 읽어주세요)

이 프로젝트는 오픈소스로 배포되지만, 여러분의 카카오 자격증명은 절대 외부로 나가지 않습니다. 다음 원칙을 지켜주세요.

1. .env 파일을 절대 커밋하지 마세요. .gitignore로 차단되어 있지만, fork 후 실수로 커밋하지 않도록 주의하세요.
2. OAuth 토큰은 자동으로 ~/.kakao-moment-mcp/tokens.json 에 저장됩니다 (파일 권한 0600). 이 경로는 홈 디렉토리이며 레포 외부입니다.
3. REST API Key, Client Secret 은 본인의 카카오 디벨로퍼스 앱에서 발급한 본인만의 키입니다. Slack/이메일/이슈/PR/스크린샷에 노출하지 마세요.
4. 시크릿이 유출되었다면 즉시 카카오 디벨로퍼스 콘솔에서 Client Secret을 재발급하고 토큰을 폐기하세요.

---

📦 설치 (60초) — OS 별 안내

광고 운영자(비개발자) 기준입니다. 터미널을 처음 열어도 두 줄만 복붙하면 끝납니다.

1) uv 설치 (한 번만)

macOS

# Homebrew 가 있다면
brew install uv
# 없다면
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

설치 후 새 PowerShell 창을 다시 여세요. (PATH 갱신이 필요합니다.)

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

참고: Linux 에는 Claude Desktop 앱이 없습니다. Claude Code(CLI) / Cursor / Cline(VSCode 확장) 에서는 동일하게 동작합니다.

2) 한 줄 setup (모든 OS·모든 클라이언트 공통)

uvx --from kakao-moment-mcp kakao-moment-mcp-setup

대화형 마법사가 자동으로:

1. 카카오 자격증명 입력 (REST API Key, Client Secret, 광고계정 ID)
2. ~/.kakao-moment-mcp/.env 저장 (chmod 0600)
3. 브라우저 OAuth 인증 → 토큰 저장 (chmod 0600)
4. 설치된 MCP 클라이언트를 자동 감지해서 등록:
   • Claude Desktop (macOS / Windows)
   • Claude Code (CLI) — claude mcp add 실행
   • Cursor (~/.cursor/mcp.json 병합)
   • Cline (VSCode 확장 cline_mcp_settings.json 병합)
   • 모든 병합은 기존 설정 보존 + .bak 백업

→ 끝나면 사용하는 클라이언트를 재시작 하기만 하면 됩니다. JSON 편집 X, clone X, pip install X.

문제가 생기면 한 줄로 진단:

uvx --from kakao-moment-mcp kakao-moment-mcp-doctor

로그는 ~/.kakao-moment-mcp/logs/server.jsonl 에 자동으로 쌓입니다(7일 보관).

데스크탑 앱만 쓰시는 분 기준 워크플로우:

1. uv 설치 (Homebrew, MSI 인스톨러 등)
2. 터미널에서 위 한 줄 실행 후 안내대로 답하기
3. Claude Desktop 재시작 → 좌하단 🔌 아이콘에서 kakao-moment 7개 도구 확인

단계별로 진행하고 싶다면 아래 "수동 설정" 섹션 참고.

3) 동의항목(scope) 확인 / 재인증

3-1) 현재 카카오 앱에 활성화된 동의항목 보기

OAuth 한 번 한 뒤라면, 카카오 콘솔을 열지 않고도 활성 동의항목을 바로 확인할 수 있습니다.

uv run kakao-moment-mcp-test scopes

출력 예시:

ID                                  이름                       사용    동의    타입
--------------------------------------------------------------------------------
moment_account                      카카오모먼트 광고계정 조회   ✓      ✓     SERVICE
manage_kakaomoment_ad               카카오모먼트 광고 관리       ✓             SERVICE
profile_nickname                    프로필 닉네임                ✓      ✓     PRIVACY

앱에서 활성화된(using=true) 동의항목: 3 개
  KAKAO_OAUTH_SCOPES 후보 (콤마로 이어 .env 에 넣을 수 있음):
  moment_account,manage_kakaomoment_ad,profile_nickname

• 사용 ✓ = 카카오 콘솔에서 활성화 한 항목
• 동의 ✓ = 현재 사용자가 이미 동의한 항목 (없으면 재인증으로 동의 받아야 함)
• 모먼트 광고 운영에 필요한 항목이 사용 ✓ + 동의 ✓ 인지 여기서 확인하세요.

3-2) 재인증 (새 동의항목 활성화 후)

카카오 콘솔에서 새로운 동의항목을 활성화한 경우, 사용자는 재동의가 필요합니다. setup 전체를 다시 돌릴 필요는 없고 인증만 재실행하면 됩니다:

uvx --from kakao-moment-mcp kakao-moment-mcp-authorize

• 브라우저가 다시 열리고, 새로 활성화된 동의항목이 함께 표시됩니다.
• 동의 후 새 access/refresh 토큰이 ~/.kakao-moment-mcp/tokens.json 에 자동 갱신됩니다.
• 자격증명(.env), Claude Desktop 설정은 그대로 유지됩니다.

언제 재인증이 필요한가요?

• 카카오모먼트 운영 권한(moment_account, manage_kakaomoment_ad 등)이 뒤늦게 활성화된 경우
• kakao-moment-mcp-test smoke 실행 시 403 Forbidden / "권한이 없습니다" 에러가 나오는 경우
• kakao-moment-mcp-test scopes 결과에서 필요한 항목이 동의 ✓ 가 아닌 경우
• Client Secret 을 카카오 콘솔에서 재발급한 경우 (이때는 setup 전체 재실행 필요)

---

수동 설정 (마법사 대신 직접 진행할 때)

🪪 카카오 디벨로퍼스 앱 준비

이미 비즈앱 전환 및 카카오모먼트 API 권한 심사가 완료된 경우 ① ~ ⑤ 만 점검하면 됩니다.

단계	작업
① 앱 생성	카카오 디벨로퍼스 콘솔 → "애플리케이션 추가하기"
② 비즈앱 전환	앱 → 비즈니스 → 비즈앱 전환
③ 비즈니스 정보 심사	사업자 정보 등록 후 심사
④ 카카오모먼트 API 권한 신청	앱 → 카카오모먼트 → 사용 권한 신청
⑤ 동의항목 활성화	앱 → 카카오 로그인 → 동의항목 → 광고계정 관리 항목 ON
⑥ Redirect URI 등록	앱 → 카카오 로그인 → Redirect URI에 http://localhost:8765/callback 추가
⑦ Client Secret 활성화	앱 → 보안 → Client Secret 코드 생성 후 "사용"
⑧ 키 확인	앱 → 앱 키 → REST API 키 복사

---

⚙️ 환경변수 설정

자격증명은 환경변수로 주입합니다. 두 가지 방법 중 하나를 선택하세요.

방법 A — 홈 디렉토리에 .env (권장)

mkdir -p ~/.kakao-moment-mcp
cat > ~/.kakao-moment-mcp/.env <<'EOF'
KAKAO_REST_API_KEY=발급받은_REST_API_KEY
KAKAO_CLIENT_SECRET=발급받은_CLIENT_SECRET
KAKAO_REDIRECT_URI=http://localhost:8765/callback
KAKAO_AD_ACCOUNT_ID=광고계정_ID
EOF
chmod 600 ~/.kakao-moment-mcp/.env

서버는 자동으로 이 경로를 읽습니다. 이 위치는 OS 사용자별로 격리되어 있으며 .gitignore 와 무관합니다.

방법 B — Claude Desktop config 의 env 키

자격증명을 claude_desktop_config.json 의 env 항목에 직접 넣을 수도 있습니다 (아래 "Claude Desktop 등록" 참고). 단, config 파일도 절대 공개 저장소에 올리지 마세요.

---

🔑 OAuth 최초 인증 (1회)

uvx 가 자동으로 패키지를 받아 인증 CLI 를 실행합니다.

uvx --from kakao-moment-mcp kakao-moment-mcp-authorize

진행 과정:

1. 터미널에 안내 URL 출력 + 브라우저 자동 오픈
2. 카카오 계정 로그인 → 동의항목 승인
3. http://localhost:8765/callback 으로 자동 리다이렉트 → 코드 캡처
4. 코드 ↔ access/refresh token 교환
5. ~/.kakao-moment-mcp/tokens.json 에 저장 (권한 0600)
6. "✅ 인증 완료" 메시지

이후 access token 이 만료되더라도 refresh token 으로 자동 갱신되므로 재인증할 필요가 없습니다.

---

🖥️ Claude Desktop 등록

Claude Desktop 의 설정 파일 위치:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

아래 내용을 추가하세요. (mcpServers 키가 이미 있다면 그 안에 kakao-moment 항목만 추가.)

{
  "mcpServers": {
    "kakao-moment": {
      "command": "uvx",
      "args": ["kakao-moment-mcp"]
    }
  }
}

💡 환경변수를 config 에 직접 넣고 싶다면 (방법 B):

{
  "mcpServers": {
    "kakao-moment": {
      "command": "uvx",
      "args": ["kakao-moment-mcp"],
      "env": {
        "KAKAO_REST_API_KEY": "...",
        "KAKAO_CLIENT_SECRET": "...",
        "KAKAO_AD_ACCOUNT_ID": "..."
      }
    }
  }
}

설정 후 Claude Desktop을 완전히 종료한 뒤 재시작하세요. 좌하단 🔌 아이콘에 kakao-moment 도구 7개가 보이면 성공입니다.

---

💬 사용 예시 (자연어 명령)

Claude Desktop 채팅창에 그대로 입력해 보세요.

📊 모니터링

어제 캠페인별 성과 요약해줘

→ get_performance_report(target=campaign, date_from=어제, date_to=어제)

오늘 일예산 얼마나 썼어?

→ get_today_status()

최근 7일 ROAS 가장 좋은 광고그룹 5개 알려줘

→ list_adgroups() + get_performance_report(target=adgroup, breakdown=day, 최근7일)

지난주 대비 성과 변화 알려줘

→ get_performance_report 두 번 호출 후 Claude 가 비교

💰 잔액 / 계정

지금 비즈머니 잔액 얼마야?

→ get_bizmoney()

광고계정 상태 알려줘

→ get_ad_account_info()

📋 구조 확인

ON 상태인 캠페인만 보여줘

→ list_campaigns(status_filter="ON")

캠페인 X의 광고그룹들 보여줘

→ list_adgroups(campaign_id="X")

어제 클릭률 낮은 소재 보여줘

→ list_creatives() + get_performance_report(target=creative)

---

🧪 로컬 테스트 (배포 전)

Claude Desktop 에 연결하기 전, CLI 로 직접 도구를 호출해 인증/응답을 검증할 수 있습니다.

# 1) 도구 목록 확인
uv run kakao-moment-mcp-test list

# 2) 인자 없는 도구
uv run kakao-moment-mcp-test call get_ad_account_info
uv run kakao-moment-mcp-test call get_bizmoney
uv run kakao-moment-mcp-test call get_today_status

# 3) 인자 있는 도구
uv run kakao-moment-mcp-test call list_campaigns --arg status_filter=ON
uv run kakao-moment-mcp-test call list_adgroups  --arg campaign_id=12345
uv run kakao-moment-mcp-test call get_performance_report \
  --arg target=campaign --arg date_from=2026-05-10 --arg date_to=2026-05-10

# 또는 JSON 한 번에
uv run kakao-moment-mcp-test call get_performance_report \
  --json '{"target":"campaign","date_from":"2026-05-10","date_to":"2026-05-10"}'

# 4) 핑 테스트: 모든 조회 도구를 한 번에 (인증/네트워크/스키마 어긋남 빠르게 확인)
uv run kakao-moment-mcp-test smoke

Claude Code(CLI)에서 자연어로 테스트

PyPI 배포 전이라도 Claude Code 에서 이 로컬 MCP 서버를 그대로 붙여 테스트할 수 있습니다.

claude mcp add kakao-moment \
  -- uv --directory /path/to/kakao-moment-mcp run kakao-moment-mcp

또는 프로젝트 루트에 .mcp.json 을 만들고:

{
  "mcpServers": {
    "kakao-moment": {
      "command": "uv",
      "args": ["--directory", ".", "run", "kakao-moment-mcp"]
    }
  }
}

등록 후 claude 세션에서 자연어로 호출:

• "광고계정 정보 알려줘"
• "어제 캠페인별 성과 요약해줘"

---

🩺 트러블슈팅

증상	원인 / 해결
KAKAO_REST_API_KEY is required	.env 가 없거나 경로 인식 실패. ~/.kakao-moment-mcp/.env 위치/권한 확인
인증 후 브라우저가 "리다이렉트 URI 불일치"	카카오 디벨로퍼스 → Redirect URI 에 http://localhost:8765/callback 추가
Claude 에서 도구가 안 보임	Claude Desktop 완전 종료 후 재시작. config JSON 문법 검증
401 Unauthorized	토큰 만료 후 refresh 실패. kakao-moment-mcp-authorize 재실행
403 Forbidden	동의항목/광고계정 권한 미허용. 카카오 디벨로퍼스에서 scope 활성화 확인
429 Too Many Requests	자동 백오프 후 재시도. 빈도 너무 잦으면 잠시 대기
비즈머니 조회 시 잔액 부족 응답	API 권한 그룹에 비즈머니 조회 포함 여부 확인

---

🗺️ 로드맵

• v0.1 (현재) — Phase 1: 조회/리포트 도구 7개
• v0.2 — Phase 2: ON/OFF 제어 (캠페인/광고그룹/소재) + Dry-run + 변경 로그
• v0.3 — Phase 3: 일예산/입찰 조정 + 변경 상한선 (±50%, 절대 상한)
• v0.4 — Phase 4: 소재 생성/수정/삭제 (광고 유형별)
• v0.5+ — DXT (Desktop Extension) 패키징, 멀티 계정 지원

---

🤝 기여

이슈/PR 환영합니다. 기여 시:

git clone https://github.com/jun7680/kakao-moment-mcp.git
cd kakao-moment-mcp
uv sync --extra dev
uv run pytest

PR 보내기 전:

• uv run ruff check src tests
• uv run pytest
• .env / tokens.json 이 staged 에 없는지 확인

---

📜 라이선스

MIT