kakao-moment-mcp 0.1.2

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

Kakao Moment MCP

Claude / Cursor / Cline 등 AI 에이전트에서 자연어로 카카오모먼트 광고를 운영합니다.

💬 "어제 캠페인별 성과 요약해줘" · "오늘 일예산 얼마나 썼어?" · "최근 7일 ROAS 좋은 광고그룹 5개"

↑ 이런 문장을 AI 에 그대로 던지면 카카오모먼트 API 를 알아서 호출해 답합니다.

---

🎯 동작 방식

flowchart LR
    U([👤 광고 운영자]) -- "자연어 질문" --> A[🤖 AI 에이전트<br/>Claude · Cursor · Cline · Claude Code]
    A -- "MCP 도구 호출" --> S[⚙️ kakao-moment-mcp<br/>로컬 실행]
    S -- "OAuth Bearer + adAccountId" --> K[(☁️ Kakao Moment API)]
    K -- "JSON" --> S
    S -- "summary 한국어 + 정규화 응답" --> A
    A -- "한국어 답변" --> U

자격증명·토큰은 사용자 홈 디렉토리 (~/.kakao-moment-mcp/) 에만 저장됩니다. 레포·로그·서버 어디로도 나가지 않습니다.

---

✨ Phase 1 — 조회/리포트 도구 7개

도구	한 줄 설명	대표 질문
get_ad_account_info	광고계정 정보·상태·잔액부족 여부	"광고계정 잘 돌아가?"
get_bizmoney	비즈머니 잔액 + 최근 7일 추이 + 잔여일 추정	"비즈머니 며칠치 남았어?"
get_today_status	오늘 누적 소진·시간당 페이스·마감 예상 소진율	"오늘 일예산 얼마나 썼어?"
list_campaigns	캠페인 목록(이름·상태·일예산·타입)	"켜져 있는 캠페인만"
list_adgroups	광고그룹(입찰가·일예산·집행기간·디바이스)	"그룹 입찰가 얼마야?"
list_creatives	소재(포맷·심사상태·미리보기·랜딩URL)	"반려된 소재 있어?"
get_performance_report	기간/단위별 성과(노출·클릭·비용·전환·CTR·CPC·ROAS)	"어제 캠페인별 성과"

🚧 Phase 2 (ON/OFF) · Phase 3 (예산/입찰 조정) · Phase 4 (소재 관리) 는 안정성 검증 후 추가됩니다. Write 도구는 항상 dry_run + 변경 상한선이 강제됩니다.

---

📦 설치

🖱️ 옵션 A — 딸깍 하면 끝

본인 OS 의 인스톨러 파일을 다운로드해 더블클릭 하세요. 터미널이 자동으로 열리며 모든 과정을 안내합니다.

OS	파일	비고
🍎 macOS	install-macos.command	첫 실행 시 Gatekeeper 차단되면 우클릭 → 열기
🪟 Windows	install-windows.bat	SmartScreen 경고 시 추가 정보 → 실행
🐧 Linux	install-linux.sh	chmod +x 후 더블클릭 또는 bash install-linux.sh

인스톨러가 하는 일: uv 자동 설치 → kakao-moment-mcp-setup 마법사 실행 (자격증명·OAuth·클라이언트 등록).

⌨️ 옵션 B — 명령어 (개발자 친화) — OS 별 탭

본인 OS 탭을 클릭하면 두 줄 복붙으로 끝입니다.

🍎 macOS

# 1) uv 설치 (둘 중 하나)
brew install uv
# 또는
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2) 한 줄 setup
uvx --from kakao-moment-mcp kakao-moment-mcp-setup

🪟 Windows (PowerShell)

# 1) uv 설치
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 새 PowerShell 창을 다시 여세요 (PATH 갱신 필요)

# 2) 한 줄 setup
uvx --from kakao-moment-mcp kakao-moment-mcp-setup

🐧 Linux

# 1) uv 설치
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2) 한 줄 setup
uvx --from kakao-moment-mcp kakao-moment-mcp-setup

ℹ️ Linux 에는 Claude Desktop 앱이 없습니다. Claude Code(CLI) · Cursor · Cline(VSCode 확장) 에서는 모두 동작합니다.

setup 마법사가 자동으로 하는 일

1. 카카오 자격증명 입력 → ~/.kakao-moment-mcp/.env 저장 (chmod 0600)

2. 브라우저 OAuth 인증 → 토큰 저장 (chmod 0600)

3. 설치된 MCP 클라이언트를 감지해서 자동 등록 (기존 설정 보존 + .bak 백업):

   클라이언트	등록 방식
   Claude Desktop	claude_desktop_config.json 병합
   Claude Code	claude mcp add 자동 실행
   Cursor	~/.cursor/mcp.json 병합
   Cline (VSCode)	cline_mcp_settings.json 병합

→ 사용하는 클라이언트를 재시작 하면 kakao-moment 도구 7개가 보입니다.

문제 생기면 한 줄로 진단

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

env / 토큰 / 로그 디렉토리 / 클라이언트 등록 상태를 ✅/❌ 로 체크리스트 출력. 로그는 ~/.kakao-moment-mcp/logs/server.jsonl (자정 회전, 7일 보관).

✅ 여기까지 끝났으면 설치 완료입니다. 바로 💬 사용 예시 로 넘어가세요.

---

🖥️ MCP 클라이언트별 등록 (수동) — 옵션, 건너뛰어도 됨

⚠️ 이 섹션은 선택입니다. 위의 kakao-moment-mcp-setup 마법사가 이미 자동으로 다 등록했습니다. 다음 경우에만 보세요:

• 마법사를 건너뛰고 직접 JSON 으로 등록하고 싶다
• 마법사가 지원하지 않는 새로운 MCP 클라이언트를 쓴다
• 자동 등록이 실패해서 수동으로 처리해야 한다

Claude Desktop (macOS · Windows)

설정 파일 위치:

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

mcpServers 키 아래에 다음을 추가:

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

저장 후 Claude Desktop 을 완전 종료 후 재시작 하면 좌하단 🔌 아이콘에 도구 7개가 보입니다.

Claude Code (CLI · 모든 OS)

claude mcp add kakao-moment -- uvx kakao-moment-mcp

또는 PyPI 배포 전이라 로컬 체크아웃으로 붙이려면:

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

Cursor (모든 OS)

~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json) 에 다음을 추가:

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

Cursor 재시작 → MCP 서버 패널에서 도구 확인.

Cline (VSCode 확장)

VSCode 확장 설정 파일:

• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

같은 mcpServers JSON 구조를 추가하면 됩니다.

---

💬 사용 예시 (자연어 → 도구)

AI 채팅창에 그대로 입력해 보세요. 도구 선택은 AI 가 알아서 합니다.

자연어 질문	호출되는 도구
"광고계정 상태 어때?"	get_ad_account_info()
"비즈머니 얼마 남았어?" / "며칠치 남았어?"	get_bizmoney()
"오늘 일예산 얼마나 썼어?" / "지금 페이스 어때?"	get_today_status()
"ON 상태인 캠페인만 보여줘"	list_campaigns(status_filter="ON")
"캠페인 X 의 광고그룹 보여줘"	list_adgroups(campaign_id="X")
"광고그룹 Y 의 소재 / 반려된 소재 있어?"	list_creatives(adgroup_id="Y")
"어제 캠페인별 성과 요약"	get_performance_report(target="campaign", date_from=어제, date_to=어제)
"최근 7일 ROAS 좋은 광고그룹 5개"	list_adgroups + get_performance_report(target="adgroup")
"지난주 대비 이번주 성과 변화"	get_performance_report 두 번 호출 후 AI 비교

각 도구는 한국어 summary 1줄을 함께 반환하므로 AI 답변이 자연스럽습니다.

---

🩺 트러블슈팅

증상	원인 / 해결
KAKAO_REST_API_KEY is required	.env 누락. kakao-moment-mcp-doctor 로 위치 확인
인증 후 "리다이렉트 URI 불일치"	카카오 디벨로퍼스 → Redirect URI 에 http://localhost:8765/callback 등록
AI 에서 도구가 안 보임	클라이언트 완전 종료 후 재시작. config JSON 문법 검증
401 Unauthorized	토큰 만료. kakao-moment-mcp-authorize 재실행
403 Forbidden	카카오 디벨로퍼스에서 동의항목 + 광고계정 권한 활성화
429 Too Many Requests	자동 backoff 재시도 됨. 호출 빈도 줄이거나 잠시 대기
비즈머니 잔액이 null	광고계정이 잔액부족 상태(isOutOfBalance: true) 일 수 있음

추가 진단:

# 활성 동의항목 확인
uv run kakao-moment-mcp-test scopes

# 모든 조회 도구 핑 테스트
uv run kakao-moment-mcp-test smoke

# 진단 + 라이브 API 호출
uvx --from kakao-moment-mcp kakao-moment-mcp-doctor --live

---

🔐 보안

• .env / tokens.json 은 ~/.kakao-moment-mcp/ 하위에 0600 권한으로 저장. 레포 외부.
• 모든 로그는 stderr + 파일 (logs/server.jsonl). stdout 은 MCP 프로토콜 전용이라 절대 로그 흐르지 않음.
• 호출 로그에는 시크릿이 기록되지 않습니다 (method/path/status/duration/request_id 만).
• 시크릿 노출 의심 시: 카카오 디벨로퍼스 → Client Secret 재발급 → kakao-moment-mcp-authorize 재실행.

자세한 정책은 SECURITY.md.

---

🔧 고급 (접이식)

수동 환경변수 설정

setup 마법사 대신 직접 .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

카카오 디벨로퍼스 앱 준비 순서

단계	작업
① 앱 생성	카카오 디벨로퍼스 콘솔
② 비즈앱 전환	앱 → 비즈니스 → 비즈앱 전환
③ 비즈니스 정보 심사	사업자 정보 등록 후 심사
④ 카카오모먼트 API 권한 신청	앱 → 카카오모먼트 → 사용 권한 신청
⑤ 동의항목 활성화	앱 → 카카오 로그인 → 동의항목
⑥ Redirect URI 등록	http://localhost:8765/callback
⑦ Client Secret 활성화	앱 → 보안 → Client Secret
⑧ REST API 키 확인	앱 → 앱 키 → REST API 키 복사

CLI 로 직접 도구 호출

uv run kakao-moment-mcp-test list                 # 도구 목록
uv run kakao-moment-mcp-test call get_today_status
uv run kakao-moment-mcp-test call list_campaigns --arg status_filter=ON
uv run kakao-moment-mcp-test call get_performance_report \
  --json '{"target":"campaign","date_from":"2026-05-10","date_to":"2026-05-10"}'
uv run kakao-moment-mcp-test smoke                # 7개 도구 한 번에

환경변수 전체 목록

변수	기본값	설명
KAKAO_REST_API_KEY	(필수)	카카오 디벨로퍼스 앱 REST API 키
KAKAO_CLIENT_SECRET	(필수)	앱 Client Secret
KAKAO_AD_ACCOUNT_ID	(필수)	광고계정 ID (숫자)
KAKAO_REDIRECT_URI	http://localhost:8765/callback	OAuth 콜백
KAKAO_OAUTH_SCOPES	(비움)	카카오 콘솔의 활성 동의항목 자동 사용
KAKAO_MCP_LOG_LEVEL	INFO	DEBUG / INFO / WARNING / ERROR
KAKAO_MCP_LOG_DIR	~/.kakao-moment-mcp/logs	파일 로그 경로

---

🗺️ 로드맵

• 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) 패키징, 멀티 계정 지원

---

🤝 기여 / 라이선스

• 기여 가이드: CONTRIBUTING.md
• 보안 정책: SECURITY.md
• 변경 이력: CHANGELOG.md
• 라이선스: MIT