KonQuest Meta Ads MCP

Claude Code를 위한 감독형 Meta 광고 운영 체제. 프리미엄 버전은 여기에서 확인할 수 있습니다: https://farasokster.gumroad.com/l/konquest-meta-ads-mcp-premium

오픈 코어 모델

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

공개 버전 (본 저장소) - 57개 도구, MIT 라이선스:

• 캠페인, 광고 세트, 광고에 대한 전체 CRUD

• 멀티 에셋 광고 생성 (동영상 + 정적 이미지, 다차원)

• 이미지 업로드 및 검색

• 캠페인 및 광고 세트 복제

• 인사이트 및 대량 계정 간 분석

• 픽셀 및 추적 진단 (5개 도구)

• 카탈로그 및 DPA 지원 (제품 세트 생성/업데이트 포함 6개 도구)

• 전체 타겟팅 툴킷 (6개 도구)

• 설정 준비 상태 검사기 (수정 지침이 포함된 42개 이상의 검사)

• 검증 파이프라인, 명명 규칙 강제, 쓰기 후 검증

• 안전 계층, 속도 제한, 롤백 참조

• 215개의 자동화된 테스트

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

• 자문 최적화 엔진 (검토 대기열, 학습, 실험, 예산 관리자, 크리에이티브 로테이션)

• 볼트 인텔리전스 및 카피 생성 (브랜드 보이스, ICP 타겟팅, 컨셉 선택)

• 그리스어 QA (그리스어식 영어 감지, 맞춤법 검사)

• 자동화 제품군 (진단, 대량 작업, 계정 감사)

• 볼트 부트스트랩 (클라이언트당 15개 템플릿 파일)

• 프리미엄 테스트 및 평가

프리미엄 번들은 별도로 제공됩니다. 공개 도구는 프리미엄 번들 없이도 완전히 작동합니다.

차별점

• 실제 예산과 엣지 케이스를 다루는 37개 이상의 클라이언트 캠페인에서 프로덕션 테스트 완료

• 단순 래퍼가 아님 - 최적화 엔진, 안전 게이트, 검증기 및 롤백 포함

• 볼트 통합 - 클라이언트 인텔리전스(ICP, 브랜드 보이스, 앵글)를 읽어 더 나은 광고 생성

• 그리스어 QA 내장 (모든 언어 검증에 맞게 조정 가능)

• 모든 광고는 일시 중지된 상태로 생성 - 운영자의 명시적인 승인 없이는 라이브로 전환되지 않음

• 자율형이 아닌 감독형 - 운영자가 모든 쓰기, 활성화, 예산 변경을 확인

도구 분류

아키텍처

meta_ads_mcp/
  core/          # 66 tools - API read/write operations
  engine/        # 32 tools - optimization, review, learning, experiments
  validators/    # Quality gates (compliance, creative specs, tracking, structure)
  safety/        # Rate limiting, rollback, duplicate checking, file locks, tier access
  ingestion/     # Internal: video manifest management
  reporting/     # Internal: not currently active (see Non-Shipped Code)

도구 카테고리

엔진 기능

• 최적화 루프 - 성과 신호에 기반한 자동 예산 조정

• 실험 관리 - 통계적 유의성을 포함한 A/B 테스트 추적

• 예산 관리자 - 구성 가능한 일일/평생 한도로 과도한 지출 방지

• 크리에이티브 로테이션 - 피로도 감지 및 자동 크리에이티브 새로고침 트리거

• 정책 학습 - 작업 결과를 추적하고 시간이 지남에 따라 신뢰도 조정

• 명명 게이트 - API 쓰기 전 명명 규칙의 엄격한 강제

안전 기능

• 속도 제한 - 백오프를 통해 Meta API 속도 제한 준수

• 롤백 - 실행 저널을 통해 최근 변경 사항 실행 취소

• 중복 확인 - 실수로 인한 캠페인/광고 중복 생성 방지

• 파일 잠금 - 볼트 저장소에 대한 안전한 동시 액세스

• 계층 기반 액세스 - 계정별 안전 계층(샌드박스, 표준, 프로덕션)

검증기 제품군

• 규정 준수 검증기 - Meta 광고 정책 사전 확인

• 크리에이티브 사양 검증기 - 이미지/동영상 크기 및 형식 검증

• 추적 검증기 - 출시 전 픽셀 및 이벤트 확인

• 구조 검증기 - 캠페인 구조 일관성 검사

• 운영 검증기 - 예산, 일정 및 타겟팅 타당성 검사

미포함 코드

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

• reporting/templates.py, reporting/formatter.py - 런타임에 가져오지 않으며 활성 보고서 생성 없음

• evals/ - 내부 평가 스텁, 운영자용 아님

• 내부 도우미 (MCP 도구 아님): identity.py (IG 해결), api.py (HTTP 클라이언트), auth.py (토큰 검증), utils.py (형식 도우미), safety/ (속도 제한기, 롤백, 중복 제거), validators/ (쓰기 전 검증 파이프라인)

설정

1. 설치

cd meta-ads-mcp
uv sync

2. 환경 변수

.env.example을 .env로 복사하고 값을 입력하세요:

cp .env.example .env

필수:

• META_ACCESS_TOKEN - Meta 마케팅 API 액세스 토큰 (시스템 사용자 토큰 권장)

선택 사항:

• META_APP_SECRET - appsecret_proof용 (프로덕션 권장)

• META_APP_ID - Meta 앱 ID

• VAULT_PATH - 마케팅 볼트 디렉토리 경로 (기본값: ~/marketing-vault)

3. MCP 구성

Claude Code MCP 구성(.mcp.json)에 추가하세요:

{
  "mcpServers": {
    "meta-ads": {
      "command": "uv",
      "args": ["--directory", "/path/to/meta-ads-mcp", "run", "python", "-m", "meta_ads_mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_token_here",
        "VAULT_PATH": "/path/to/your/marketing-vault"
      }
    }
  }
}

4. 볼트 구조 (선택 사항)

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

your-vault/
  01_CLIENTS/{client-slug}/
    00-profile.md        # Account IDs, pixel, page, IG
    02-icp-personas.md   # Target audience profiles
    04-brand-voice.md    # Tone, language, style rules
    05-messaging-house.md # Angles, value props
    08-objections.md     # Objections + bias deployment
    matrix.md            # Decision Matrix
  02_COMPETITORS/{slug}/
    landscape.md         # Competitive landscape

테스트

uv run --extra dev python -m pytest tests/ -v
# Public package: 215 passed | Full (with premium): 246 passed

라이선스

MIT - LICENSE 참조.