brandu-mos/konquest-meta-ads-mcp

Claude 코드를 위한 지도 학습(Supervised) Meta Ads 운영 시스템입니다. 프리미엄 버전은 여기에서 찾을 수 있습니다: https://farasokster.gumroad.com/l/konquest-meta-ads-mcp-premium

KonQuest Meta Ads MCP는 오픈 코어 모델을 사용합니다:

공개(이 레포) - 57개의 도구, MIT 라이선스:

• 캠페인, 광고 세트, 광고에 대한 전체 CRUD 기능
• 다중 자산 광고 생성 (비디오 + 정적 이미지, 다차원)
• 이미지 업로드 및 검색
• 캠페인 및 광고 세트 복제
• 인사이트 및 대규모 계정 간 분석(cross-account analytics)
• 픽셀 및 추적 진단 도구 (5개)
• 카탈로그 및 DPA 지원 (제품 세트 생성/업데이트를 포함하여 6개 도구)
• 전체 타겟팅 툴킷 (6개 도구)
• 설정 준비 상태 확인기 (수정 지침이 있는 42가지 이상의 체크 항목)
• 유효성 검사 파이프라인, 명명 규칙 강제 적용, 게시 후 검증
• 안전 계층(Safety tiers), 속도 제한(rate limiting), 롤백 참조
• 215개의 자동화 테스트

프리미엄 번들 - 41개 도구 추가:

• 자문 최적화 엔진 (검토 대기열, 학습, 실험, 예산 관리자, 크리에이티브 로테이션)
• 금고(Vault) 인텔리전스 및 카피 생성 (브랜드 보이스, ICP 타겟팅, 컨셉 선택)
• 그리스어 언어 QA (Greeklish 감지, 철자 검사)
• 자동화 스위트 (진단 도구, 대규모 작업, 계정 감사)
• 금고 부트스트랩 (클라이언트당 15개 템플릿 파일)
• 프리미엄 테스트 및 평가

프리미엄 번들은 별도로 구매할 수 있습니다. 공개 도구는 이것 없이도 완벽하게 작동합니다.

실제 예산과 실제 엣지 케이스를 가진 37개 이상의 클라이언트 캠페인에서 테스트됨 래퍼(wrapper)가 아님 - 최적화 엔진, 안전 게이트, 검증기, 롤백 기능을 포함함 금고 통합(Vault-integrated) - 클라이언트 인텔리전스(ICP, 브랜드 보이스, 각도)를 읽어 더 나은 광고를 생성함 그리스어 언어 QA가 내장되어 있음 (모든 언어 검증에 적응 가능) 생성된 모든 광고는 일시 중지됨(PAUSED) - 명시적인 운영자 승인 없이는 아무것도 활성화되지 않음 지도 학습이며, 자율적이지 않음(Supervised, not autonomous) - 운영자가 모든 쓰기 작업, 모든 활성화, 모든 예산 변경을 확인합니다.

meta_ads_mcp/
core/ # 66 도구 - API 읽기/쓰기 작업
engine/ # 32 도구 - 최적화, 검토, 학습, 실험
...

속도 제한(Rate limiting) - 백오프(backoff)를 사용하여 Meta API 속도 제한 준수
롤백(Rollback) - 실행 저널로 최근 변경 사항 되돌리기
중복 확인(Duplicate checking) - 실수로 인한 중복 캠페인/광고 방지
파일 잠금(File locks) - 볼트 스토리지에 대한 안전한 동시 접근
티어 기반 접근(Tier-based access) - 계정별 안전 등급 (샌드박스, 표준, 프로덕션)

규정 준수 검증기(Compliance validator) - Meta 광고 정책 사전 확인
크리에이티브 사양 검증기(Creative spec validator) - 이미지/비디오 치수 및 형식 유효성 검사
추적 검증기(Tracking validator) - 출시 전 픽셀 및 이벤트 검증
구조 검증기(Structure validator) - 캠페인 구조 일관성 확인
운영 검증기(Operational validator) - 예산, 일정, 타겟팅 건전성 확인

저장소에 존재하지만 활성 도구 표면(active tool surface)의 일부는 아닌 코드:

reporting/templates.py, reporting/formatter.py- 런타임에 임포트되지 않으며, 활성 보고서 생성 기능이 아님evals/- 내부 평가 스텁(stub)으로, 운영자에게 노출되는 기능이 아님내부 도우미(MCP 도구 아님): identity.py (IG 해상도), api.py (HTTP 클라이언트), auth.py (토큰 검증), utils.py (형식 도움말), safety/ (속도 제한기, 롤백, 중복 제거), validators/ (사전 작성 유효성 검사 파이프라인)**

cd meta-ads-mcp
uv sync

.env.example를 .env로 복사하고 다음 값들을 채우세요:

cp .env.example .env

필수 항목:

META_ACCESS_TOKEN

• Meta Marketing API 액세스 토큰 (시스템 사용자 토큰 권장)

선택 항목:

META_APP_SECRET

• appsecret_proof용 (프로덕션 환경에 권장)META_APP_ID
• Meta 앱 IDVAULT_PATH
• 마케팅 볼트 디렉터리의 경로 (기본값: ~/marketing-vault)

Claude Code MCP 설정 파일(.mcp.json)에 추가하세요:

{
"mcpServers": {
"meta-ads": {
...

클라이언트 인텔리전스용 볼트 통합을 사용하는 경우:

your-vault/
01_CLIENTS/{client-slug}/
00-profile.md # 계정 ID, 픽셀, 페이지, IG
...

uv run --extra dev python -m pytest tests/ -v
# 공개 패키지: 215개 통과 | 전체 (프리미엄 포함): 246개 통과

MIT - LICENSE 참조.