Metadata-Version: 2.4
Name: kakao-moment-mcp
Version: 0.1.1
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

# Kakao Moment MCP

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

> "어제 캠페인별 성과 요약해줘", "오늘 일예산 얼마나 썼어?", "최근 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. 시크릿이 유출되었다면 즉시 [카카오 디벨로퍼스 콘솔](https://developers.kakao.com/console/app)에서 Client Secret을 재발급하고 토큰을 폐기하세요.

---

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

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

### 1) `uv` 설치 (한 번만)

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

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

</details>

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

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

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

</details>

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

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

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

</details>

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

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

> 문제가 생기면 한 줄로 진단:
> ```bash
> uvx --from kakao-moment-mcp kakao-moment-mcp-doctor
> ```
> 로그는 `~/.kakao-moment-mcp/logs/server.jsonl` 에 자동으로 쌓입니다(7일 보관).

> 데스크탑 앱만 쓰시는 분 기준 워크플로우:
> 1. [uv 설치](https://docs.astral.sh/uv/getting-started/installation/) (Homebrew, MSI 인스톨러 등)
> 2. 터미널에서 위 한 줄 실행 후 안내대로 답하기
> 3. Claude Desktop 재시작 → 좌하단 🔌 아이콘에서 `kakao-moment` 7개 도구 확인
>
> 단계별로 진행하고 싶다면 아래 "수동 설정" 섹션 참고.

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

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

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

```bash
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 전체를 다시 돌릴 필요는 없고 **인증만** 재실행하면 됩니다:

```bash
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 권한 심사가 완료된 경우 ① ~ ⑤ 만 점검하면 됩니다.

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

---

## ⚙️ 환경변수 설정

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

### 방법 A — 홈 디렉토리에 `.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
```

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

### 방법 B — Claude Desktop config 의 `env` 키

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

---

## 🔑 OAuth 최초 인증 (1회)

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

```bash
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` 항목만 추가.)

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

> 💡 환경변수를 config 에 직접 넣고 싶다면 (방법 B):
> ```jsonc
> {
>   "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 로 직접 도구를 호출해 인증/응답을 검증할 수 있습니다.

```bash
# 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 서버를 그대로 붙여 테스트할 수 있습니다.

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

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

```jsonc
{
  "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 환영합니다. 기여 시:

```bash
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](./LICENSE)
