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개

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

📦 설치

🖱️ 옵션 A — 딸깍 하면 끝

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

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

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

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

# 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

# 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

# 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 클라이언트를 쓴다

• 자동 등록이 실패해서 수동으로 처리해야 한다

설정 파일 위치:

• 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 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/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json) 에 다음을 추가:

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

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

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 가 알아서 합니다.

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

🩺 트러블슈팅

추가 진단:

# 활성 동의항목 확인
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

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개 도구 한 번에

🗺️ 로드맵

• 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