Meta Ads MCP

메타 광고 MCP

Meta Ads API와 상호 작용하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 도구를 사용하면 AI 모델이 표준화된 인터페이스를 통해 Meta 광고 캠페인에 액세스, 분석 및 관리할 수 있습니다. 이를 통해 LLM은 성과 데이터를 검색하고, 광고 크리에이티브를 시각화하고, Facebook, Instagram 및 기타 Meta 플랫폼에 대한 전략적 인사이트를 제공할 수 있습니다.

면책 조항: 이 도구는 비공식적인 서드파티 도구이며, Meta와 어떠한 방식으로도 제휴, 보증 또는 제휴 관계가 없습니다. 이 프로젝트는 독립적으로 관리되며 Meta의 서비스 약관에 따라 공개 API를 사용합니다. Meta, Facebook, Instagram 및 기타 Meta 브랜드 이름은 해당 소유자의 상표입니다.

스크린샷 : LLM을 사용하여 광고 성과 파악:

빠른 시작

1. Pipeboard 에 가입하여 Meta로 인증하세요(또는 사용자 정의 Meta 앱을 설정할 수 있습니다)
2. pipeboard.co/api-tokens 에서 Pipeboard 토큰을 받으세요
3. MCP 클라이언트에 다음 구성을 추가하세요.

지엑스피1

이제 원하는 MCP 클라이언트에서 Meta Ads MCP를 사용할 수 있습니다.

참고 : Pipeboard 인증 대신 자체 Meta Developer 앱을 사용하려면 CUSTOM_META_APP.md에서 지침을 참조하세요.

특징

• AI 기반 캠페인 분석 : 선호하는 LLM이 캠페인을 분석하고 성과에 대한 실행 가능한 통찰력을 제공하도록 하세요.
• 전략적 권장 사항 : 광고 지출, 타겟팅 및 창의적인 콘텐츠 최적화를 위한 데이터 기반 제안을 받습니다.
• 자동 모니터링 : MCP 호환 LLM에 성과 지표를 추적하고 중요한 변경 사항에 대해 알림을 요청합니다.
• 예산 최적화 : 더 나은 성과를 내는 광고 세트에 예산을 재할당하기 위한 권장 사항을 받으세요.
• 크리에이티브 개선 : 광고 카피, 이미지 및 행동 촉구에 대한 피드백을 받습니다.
• 캠페인 관리 : 캠페인, 광고 세트 및 광고에 대한 변경 요청(모든 변경 사항에는 명시적 확인이 필요함)
• 크로스 플랫폼 통합 : Facebook, Instagram 및 모든 Meta 광고 플랫폼과 호환됩니다.
• 범용 LLM 지원 : Claude Desktop, Cursor, Cherry Studio 등을 포함한 모든 MCP 클라이언트와 호환
• 간단한 인증 : 안전한 OAuth 인증을 통한 간편한 설정
• 크로스 플랫폼 지원 : Windows, macOS 및 Linux에서 작동

고급 설정

개발 설치

프로젝트에 기여하거나 직접 실행해야 하는 경우:

개인정보 보호 및 보안

Meta Ads MCP는 다음과 같은 보안 모범 사례를 따릅니다.

1. 토큰은 플랫폼별 보안 위치에 캐시됩니다.
   • 윈도우: %APPDATA%\meta-ads-mcp\token_cache.json
   • macOS: ~/Library/Application Support/meta-ads-mcp/token_cache.json
   • 리눅스: ~/.config/meta-ads-mcp/token_cache.json
2. 각 명령에 대해 액세스 토큰을 제공할 필요는 없습니다. 캐시에서 자동으로 검색됩니다.

테스트

LLM 인터페이스 테스트

LLM 인터페이스(예: Claude)와 함께 Meta Ads MCP를 사용하는 경우:

1. PIPEBOARD_API_TOKEN 환경 변수가 설정되어 있는지 확인하세요.
2. mcp_meta_ads_get_ad_accounts 호출하여 계정 액세스를 확인하세요.
3. mcp_meta_ads_get_account_info 사용하여 특정 계정 세부 정보를 확인하세요.

문제 해결

인증 문제

인증 문제가 발생하는 경우:

1. 파이프보드 설정을 확인하세요.
   • PIPEBOARD_API_TOKEN 올바르게 설정되었는지 확인하세요.
   • Pipeboard 대시보드에서 토큰을 확인하세요
   • 새로운 로그인을 강제로 시도해 보세요: python test_pipeboard_auth.py --force-login
2. LLM 인터페이스를 사용하는 경우:
   • PIPEBOARD_API_TOKEN 환경 변수가 설정되어 있는지 확인하세요.
   • 콜백 서버가 제대로 실행되고 있는지 확인하세요

API 오류

Meta API에서 오류가 발생하는 경우:

1. 사용자에게 광고 계정에 대한 적절한 권한이 있는지 확인하세요.
2. 요금 제한이나 기타 제한 사항이 있는지 확인하세요
3. Pipeboard 토큰이 만료되지 않았는지 확인하세요.

로그 위치

로그 파일은 플랫폼별 위치에 저장됩니다.

• macOS : ~/Library/Application Support/meta-ads-mcp/meta_ads_debug.log
• Windows : %APPDATA%\meta-ads-mcp\meta_ads_debug.log
• 리눅스 : ~/.config/meta-ads-mcp/meta_ads_debug.log

구성

파이프보드 인증

Meta Ads MCP를 사용하는 가장 쉬운 방법은 Pipeboard 인증을 사용하는 것입니다.

1. Pipeboard.co 에 가입하고 API 토큰을 생성하세요
2. 환경 변수를 설정합니다.
   export PIPEBOARD_API_TOKEN=your_pipeboard_token
3. meta-ads-mcp를 실행하면 자동으로 인증이 처리됩니다.

커서 또는 Claude Desktop 사용

Claude와 통합하려면 claude_desktop_config.json 에 이것을 추가하고, Cursor와 통합하려면 ~/.cursor/mcp.json 에 이것을 추가하세요.

사용 가능한 MCP 도구

1. mcp_meta_ads_get_ad_accounts
   • 사용자가 액세스할 수 있는 광고 계정 가져오기
   • 입력:
     • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
     • user_id : 메타 사용자 ID 또는 현재 사용자의 "me"
     • limit : 반환할 최대 계정 수(기본값: 10)
   • 반환: 세부 정보가 포함된 액세스 가능한 광고 계정 목록
2. mcp_meta_ads_get_account_info
   • 특정 광고 계정에 대한 자세한 정보를 얻으세요
   • 입력:
     • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
     • account_id : Meta Ads 계정 ID(형식: act_XXXXXXXXX)
   • 반환: 지정된 계정에 대한 자세한 정보
3. mcp_meta_ads_get_account_pages
   • Meta Ads 계정과 연결된 페이지 가져오기
   • 입력:
     • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
     • account_id : 메타 광고 계정 ID(형식: act_XXXXXXXXX) 또는 현재 사용자 페이지의 경우 "me"
   • 반환: 광고 생성 및 관리에 유용한 계정과 연결된 페이지 목록
4. mcp_meta_ads_get_campaigns
   • 선택적 필터링을 사용하여 Meta Ads 계정에 대한 캠페인을 받으세요
   • 입력:
     • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
     • account_id : Meta Ads 계정 ID(형식: act_XXXXXXXXX)
     • limit : 반환할 캠페인의 최대 수(기본값: 10)
     • status_filter : 상태별로 필터링합니다(모두 비어 있는 경우 또는 '활성', '일시 중지' 등).
   • 반환: 기준과 일치하는 캠페인 목록
5. mcp_meta_ads_get_campaign_details
   • 특정 캠페인에 대한 자세한 정보를 얻으세요
   • 입력:
     • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
     • campaign_id : 메타 광고 캠페인 ID
   • 반환: 지정된 캠페인에 대한 자세한 정보
6. mcp_meta_ads_create_campaign
   • Meta Ads 계정에서 새 캠페인을 만듭니다.
   • 입력:
     • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
     • account_id : Meta Ads 계정 ID(형식: act_XXXXXXXXX)
     • name : 캠페인 이름
     • objective : 캠페인 목표(인지도, 트래픽, 참여 등)
     • status : 초기 캠페인 상태(기본값: 일시 중지됨)
     • special_ad_categories : 해당되는 경우 특별 광고 카테고리 목록
     • daily_budget : 계정 통화(센트)로 표시된 일일 예산
     • lifetime_budget : 계정 통화(센트)로 표시된 평생 예산
   • 반환: 새로운 캠페인 세부 정보 확인
7. mcp_meta_ads_get_adsets
   • 캠페인별 선택적 필터링을 통해 Meta Ads 계정에 대한 광고 세트를 가져옵니다.
   • 입력:
     • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
     • account_id : Meta Ads 계정 ID(형식: act_XXXXXXXXX)
     • limit : 반환할 광고 세트의 최대 수(기본값: 10)
     • campaign_id : 필터링할 선택적 캠페인 ID
   • 반환: 기준과 일치하는 광고 세트 목록
8. mcp_meta_ads_get_adset_details
   • 특정 광고 세트에 대한 자세한 정보를 얻으세요
   • 입력:
     • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
     • adset_id : 메타 광고 광고 세트 ID
   • 반환: 지정된 광고 세트에 대한 자세한 정보
9. mcp_meta_ads_create_adset
   • Meta Ads 계정에서 새 광고 세트를 만듭니다.
   • 입력:
     • account_id : Meta Ads 계정 ID(형식: act_XXXXXXXXX)
     • campaign_id : 이 광고 세트가 속한 메타 광고 캠페인 ID
     • name : 광고 세트 이름
     • status : 초기 광고 세트 상태(기본값: 일시 중지됨)
     • daily_budget : 문자열 형태의 계정 통화(센트)로 표현된 일일 예산
     • lifetime_budget : 문자열 형태의 계정 통화(센트)로 표현된 평생 예산
     • targeting : 타겟팅 사양(예: 연령, 위치, 관심사)
     • optimization_goal : 전환 최적화 목표(예: 'LINK_CLICKS')
     • billing_event : 청구 방식(예: '임프레션')
     • bid_amount : 계정 통화로 표시된 입찰 금액(센트)
     • bid_strategy : 입찰 전략(예: 'LOWEST_COST')
     • start_time , end_time : 선택적인 시작/종료 시간(ISO 8601)
     • access_token (선택 사항): Meta API 액세스 토큰
   • 반환: 새로운 광고 세트 세부 정보 확인
10. mcp_meta_ads_get_ads

• 선택적 필터링을 사용하여 Meta Ads 계정에 대한 광고를 받으세요
• 입력:
  • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
  • account_id : Meta Ads 계정 ID(형식: act_XXXXXXXXX)
  • limit : 반환할 광고의 최대 개수(기본값: 10)
  • campaign_id : 필터링할 선택적 캠페인 ID
  • adset_id : 필터링할 선택적 광고 세트 ID
• 반환: 기준과 일치하는 광고 목록

11. mcp_meta_ads_create_ad

• 기존 크리에이티브로 새 광고를 만듭니다.
• 입력:
  • account_id : Meta Ads 계정 ID(형식: act_XXXXXXXXX)
  • name : 광고 이름
  • adset_id : 이 광고가 배치될 광고 세트 ID
  • creative_id : 사용할 기존 크리에이티브의 ID
  • status : 초기 광고 상태(기본값: 일시 중지됨)
  • bid_amount : 선택 입찰 금액(센트)
  • tracking_specs : 선택적 추적 사양
  • access_token (선택 사항): Meta API 액세스 토큰
• 반품: 새 광고 세부 정보 확인

12. mcp_meta_ads_get_ad_details

• 특정 광고에 대한 자세한 정보를 얻으세요
• 입력:
  • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
  • ad_id : 메타 광고 광고 ID
• 반환: 지정된 광고에 대한 자세한 정보

13. mcp_meta_ads_get_ad_creatives

• 특정 광고에 대한 창의적인 세부 정보를 얻으세요
• 입력:
  • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
  • ad_id : 메타 광고 광고 ID
• 반환: 텍스트, 이미지, URL을 포함한 크리에이티브 세부 정보

14. mcp_meta_ads_create_ad_creative

• 업로드된 이미지 해시를 사용하여 새 광고 크리에이티브를 만듭니다.
• 입력:
  • account_id : Meta Ads 계정 ID(형식: act_XXXXXXXXX)
  • name : 크리에이티브 이름
  • image_hash : 업로드된 이미지의 해시
  • page_id : 광고의 Facebook 페이지 ID
  • link_url : 목적지 URL
  • message : 광고 카피/텍스트
  • headline : 광고 헤드라인
  • description : 광고 설명
  • call_to_action_type : CTA 버튼 유형(예: 'LEARN_MORE')
  • instagram_actor_id : 선택적인 Instagram 계정 ID
  • access_token (선택 사항): Meta API 액세스 토큰
• 반품: 새로운 크리에이티브 세부 정보 확인

15. mcp_meta_ads_upload_ad_image

• Meta Ads 크리에이티브에 사용할 이미지를 업로드하세요
• 입력:
  • account_id : Meta Ads 계정 ID(형식: act_XXXXXXXXX)
  • image_path : 업로드할 이미지 파일의 경로
  • name : 이미지의 선택적 이름
  • access_token (선택 사항): Meta API 액세스 토큰
• 반환: 해시를 포함한 이미지 세부 정보가 포함된 JSON 응답

16. mcp_meta_ads_get_ad_image

• 한 단계로 메타 광고 이미지를 얻고, 다운로드하고, 시각화하세요
• 입력:
  • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
  • ad_id : 메타 광고 광고 ID
• 반환: 직접 시각적 분석을 위해 준비된 광고 이미지

17. mcp_meta_ads_update_ad

• 새로운 설정으로 광고 업데이트
• 입력:
  • ad_id : 메타 광고 광고 ID
  • status : 광고 상태(활성, 일시 중지 등)를 업데이트합니다.
  • bid_amount : 계정 통화로 표시된 입찰 금액(USD의 경우 센트)
  • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
• 반환: 업데이트된 광고 세부 정보와 확인 링크가 포함된 확인

18. mcp_meta_ads_update_adset

• 빈도 제한을 포함한 새로운 설정으로 광고 세트 업데이트
• 입력:
  • adset_id : 메타 광고 광고 세트 ID
  • frequency_control_specs : 주파수 제어 사양 목록
  • bid_strategy : 입찰 전략(예: 'LOWEST_COST_WITH_BID_CAP')
  • bid_amount : 계정 통화로 표시된 입찰 금액(USD의 경우 센트)
  • status : 광고 세트 상태(활성, 일시 중지 등)를 업데이트합니다.
  • targeting : 타겟팅_자동화를 포함한 타겟팅 사양
  • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
• 반환: 업데이트된 광고 세트 세부 정보와 확인 링크가 포함된 확인

19. mcp_meta_ads_get_insights

• 캠페인, 광고 세트, 광고 또는 계정에 대한 성과 통찰력을 얻으세요
• 입력:
  • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
  • object_id : 캠페인, 광고 세트, 광고 또는 계정의 ID
  • time_range : 통찰력에 대한 시간 범위(기본값: 최대)
  • breakdown : 선택적 분석 차원(예: 연령, 성별, 국가)
  • level : 집계 레벨(광고, 광고세트, 캠페인, 계정)
• 반환: 지정된 개체에 대한 성능 측정 항목

20. mcp_meta_ads_debug_image_download

• 이미지 다운로드 문제를 디버깅하고 자세한 진단 결과를 보고합니다.
• 입력:
  • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
  • url : 테스트할 직접 이미지 URL (선택 사항)
  • ad_id : 메타 광고 광고 ID(선택 사항, url이 제공되지 않은 경우 사용됨)
• 반환: 이미지 다운로드 시도에 대한 진단 정보

21. mcp_meta_ads_get_login_link

• Meta Ads 인증을 위한 클릭 가능한 로그인 링크를 받으세요
• 입력:
  • access_token (선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
• 반환: 메타 인증을 위한 클릭 가능한 리소스 링크

22. mcp_meta-ads_create_budget_schedule

• 메타 광고 캠페인에 대한 예산 일정을 만듭니다.
• 입력:
  • campaign_id : 메타 광고 캠페인 ID.
  • budget_value : 예산 증가 금액.
  • budget_value_type : 예산 값 유형("ABSOLUTE" 또는 "MULTIPLIER").
  • time_start : 수요가 높은 기간이 시작되는 시점에 대한 Unix 타임스탬프입니다.
  • time_end : 수요가 많은 기간이 끝나야 하는 유닉스 타임스탬프입니다.
  • access_token (선택 사항): Meta API 액세스 토큰.
• 반환값: 생성된 예산 일정의 ID 또는 오류 메시지가 포함된 JSON 문자열입니다.