Metadata-Version: 2.4
Name: kakao-moment-mcp
Version: 0.1.8
Summary: Kakao Moment 광고 운영 자동화 MCP 서버 - Claude Desktop에서 자연어로 카카오모먼트 광고 조회/리포트
Project-URL: Homepage, https://github.com/jun7680/kakao-moment-mcp
Project-URL: Issues, https://github.com/jun7680/kakao-moment-mcp/issues
Author-email: 인준 <injunock@gmail.com>
License: MIT
License-File: LICENSE
Keywords: advertising,claude,kakao,kakao-moment,mcp,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: structlog>=24.1.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# Kakao Moment MCP

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

[![PyPI version](https://img.shields.io/pypi/v/kakao-moment-mcp.svg?color=blue)](https://pypi.org/project/kakao-moment-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/kakao-moment-mcp.svg)](https://pypi.org/project/kakao-moment-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![CI](https://github.com/jun7680/kakao-moment-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/jun7680/kakao-moment-mcp/actions/workflows/ci.yml)
[![MCP](https://img.shields.io/badge/MCP-Model_Context_Protocol-8A2BE2.svg)](https://modelcontextprotocol.io/)

</div>

> 💬 **"어제 캠페인별 성과 요약해줘"** · **"오늘 일예산 얼마나 썼어?"** · **"최근 7일 ROAS 좋은 광고그룹 5개"**
>
> ↑ 이런 문장을 AI 에 그대로 던지면 카카오모먼트 API 를 알아서 호출해 답합니다.

---

## 🎯 동작 방식

```mermaid
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/`) 에만 저장됩니다. 레포·로그·서버 어디로도 나가지 않습니다.

---

## ✨ 제공 도구

| 도구 | 한 줄 설명 | 대표 질문 |
| --- | --- | --- |
| `get_ad_account_info` | 광고계정 정보·상태·잔액부족 여부 | "광고계정 잘 돌아가?" |
| `get_bizmoney` | 비즈머니 잔액 + 최근 7일 추이 + 잔여일 추정 | "비즈머니 며칠치 남았어?" |
| `get_today_status` | 오늘 누적 소진·시간당 페이스·마감 예상 소진율 | "오늘 일예산 얼마나 썼어?" |
| `list_campaigns` | 캠페인 목록(이름·상태·일예산·타입) | "켜져 있는 캠페인만" |
| `list_adgroups` | 광고그룹(입찰가·일예산·집행기간·디바이스) | "그룹 입찰가 얼마야?" |
| `list_creatives` | 소재(포맷·심사상태·미리보기·랜딩URL) | "반려된 소재 있어?" |
| `get_performance_report` | 기간/단위별 성과(노출·클릭·비용·전환·CTR·CPC·ROAS) | "어제 캠페인별 성과" |
| `update_adgroup_status` | 광고그룹 ON/OFF 변경 | "광고그룹 123 꺼줘" |
| `update_adgroup_budget` | 광고그룹 일예산 변경 | "광고그룹 123 일예산 5만원으로 바꿔줘" |
| `update_adgroup_bid` | 광고그룹 입찰가 변경 | "광고그룹 123 입찰가 700원으로 바꿔줘" |
| `update_creative_status` | 소재 ON/OFF 변경 | "소재 456 꺼줘" |
| `update_campaign_budget` | 캠페인 일예산 변경 | "캠페인 9 일예산 20만원으로 바꿔줘" |
| `create_display_creative` | 디스플레이 소재 생성 | "이 소재 생성 요청 본문으로 소재 만들어줘" |

---

## 📦 설치

### 🖱️ 옵션 A — 딸깍 하면 끝

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

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

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

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

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

<details open><summary><b>🍎 macOS</b></summary>

```bash
# 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
```

</details>

<details><summary><b>🪟 Windows (PowerShell)</b></summary>

```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
```

</details>

<details><summary><b>🐧 Linux</b></summary>

```bash
# 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 확장)** 에서는 모두 동작합니다.

</details>

### 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개가 보입니다.

### 문제 생기면 한 줄로 진단

```bash
uvx --from kakao-moment-mcp kakao-moment-mcp-doctor
```

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

> ✅ **여기까지 끝났으면 설치 완료**입니다. 바로 [💬 사용 예시](#-사용-예시-자연어--도구) 로 넘어가세요.

---

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

> ⚠️ **이 섹션은 선택입니다.** 위의 `kakao-moment-mcp-setup` 마법사가 이미 자동으로 다 등록했습니다.
> 다음 경우에만 보세요:
> - 마법사를 건너뛰고 직접 JSON 으로 등록하고 싶다
> - 마법사가 지원하지 않는 새로운 MCP 클라이언트를 쓴다
> - 자동 등록이 실패해서 수동으로 처리해야 한다

<details><summary><b>Claude Desktop</b> (macOS · Windows)</summary>

설정 파일 위치:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

`mcpServers` 키 아래에 다음을 추가:

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

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

</details>

<details><summary><b>Claude Code</b> (CLI · 모든 OS)</summary>

```bash
claude mcp add kakao-moment -- uvx kakao-moment-mcp
```

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

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

</details>

<details><summary><b>Cursor</b> (모든 OS)</summary>

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

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

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

</details>

<details><summary><b>Cline</b> (VSCode 확장)</summary>

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 구조를 추가하면 됩니다.

</details>

---

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

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 비교 |
| "광고그룹 123 꺼줘" | `update_adgroup_status(adgroup_id="123", config="OFF")` |
| "광고그룹 123 일예산 5만원으로 바꿔줘" | `update_adgroup_budget(adgroup_id="123", daily_budget_amount=50000)` |
| "광고그룹 123 입찰가 700원으로 바꿔줘" | `update_adgroup_bid(adgroup_id="123", bid_amount=700)` |
| "소재 456 다시 켜줘" | `update_creative_status(creative_id="456", config="ON")` |
| "캠페인 9 일예산 20만원으로 바꿔줘" | `update_campaign_budget(campaign_id="9", daily_budget_amount=200000)` |

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

---

## ⚠️ 알려진 한계 (Windows)

### Microsoft Store 버전 Claude Desktop

Microsoft Store 에서 설치한 Claude Desktop 은 **샌드박스 안에 별도 config 경로**를 사용합니다 (`%LOCALAPPDATA%\Packages\Anthropic.Claude_*\...`). 자동 등록 스크립트가 표준 `%APPDATA%\Claude\` 경로를 우선 보기 때문에 **자동 등록이 안 될 수 있습니다.**

**해결**:
- 가능하면 [공식 다운로드 페이지](https://claude.ai/download) 에서 받은 **표준 인스톨러 버전** 사용 (권장)
- 또는 다음 명령으로 진짜 config 경로 찾기:
  ```cmd
  powershell -Command "Get-ChildItem -Path $env:USERPROFILE -Recurse -Filter 'claude_desktop_config.json' -ErrorAction SilentlyContinue | Select-Object FullName, LastWriteTime"
  ```
  → 가장 최근 수정시각 파일이 진짜. 그 파일에 직접 `kakao-moment` 항목 추가.

### Windows GUI 앱 PATH 인식

Claude Desktop 같은 GUI 앱은 사용자 PATH 에서 `uvx` 를 못 찾는 경우가 있습니다. 자동 인스톨러 `.bat` 의 3단계에서 `uvx` 의 **절대경로** (`C:\Users\xxx\.local\bin\uvx.exe`) 로 자동 보정해두지만, 수동 등록 시는 절대경로로 명시하세요:

```jsonc
{
  "mcpServers": {
    "kakao-moment": {
      "command": "C:\\Users\\사용자명\\.local\\bin\\uvx.exe",
      "args": ["kakao-moment-mcp"]
    }
  }
}
```

### 이미 손상된 config 자동 복구 불가

이전 버전 `.bat` 나 수동 편집으로 JSON 이 깨진 상태라면 자동 머지 스크립트도 파싱 실패해서 더 못 고칩니다. 그 경우 **노트패드로 직접 정정** 또는 백업본 (`*.json.bak`) 복원.

---

## 🩺 트러블슈팅

| 증상 | 원인 / 해결 |
| --- | --- |
| `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`) 일 수 있음 |

추가 진단:

```bash
# 활성 동의항목 확인
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](./SECURITY.md).

---

## 🔧 고급 (접이식)

<details><summary><b>수동 환경변수 설정</b></summary>

setup 마법사 대신 직접 `.env` 를 만들고 싶다면:

```bash
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
```

</details>

<details><summary><b>카카오 디벨로퍼스 앱 준비 순서</b></summary>

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

</details>

<details><summary><b>CLI 로 직접 도구 호출</b></summary>

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

</details>

<details><summary><b>환경변수 전체 목록</b></summary>

| 변수 | 기본값 | 설명 |
| --- | --- | --- |
| `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` | 파일 로그 경로 |

</details>

---

## 🗺️ 로드맵

- **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](./CONTRIBUTING.md)
- 보안 정책: [SECURITY.md](./SECURITY.md)
- 변경 이력: [CHANGELOG.md](./CHANGELOG.md)
- 라이선스: [MIT](./LICENSE)
