remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Integrations
Provides tools for managing and analyzing Facebook advertising campaigns, including performance metrics, campaign creation, and creative assessment.
Offers functionality to access, analyze and manage Instagram advertising campaigns through Meta's advertising platform.
Enables access to Meta's advertising APIs, allowing retrieval of ad performance data, campaign management, budget optimization, and viewing ad creatives across Meta platforms.
메타 광고 MCP
Meta Ads API와 상호 작용하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 도구를 사용하면 AI 모델이 표준화된 인터페이스를 통해 Meta 광고 캠페인에 액세스, 분석 및 관리할 수 있습니다. 이를 통해 LLM은 성과 데이터를 검색하고, 광고 크리에이티브를 시각화하고, Facebook, Instagram 및 기타 Meta 플랫폼에 대한 전략적 인사이트를 제공할 수 있습니다.
면책 조항: 이 도구는 비공식적인 서드파티 도구이며, Meta와 어떠한 방식으로도 제휴, 보증 또는 제휴 관계가 없습니다. 이 프로젝트는 독립적으로 관리되며 Meta의 서비스 약관에 따라 공개 API를 사용합니다. Meta, Facebook, Instagram 및 기타 Meta 브랜드 이름은 해당 소유자의 상표입니다.
Screenhot: LLM을 사용하여 광고 성과를 파악합니다.
특징
- AI 기반 캠페인 분석 : 선호하는 LLM이 캠페인을 분석하고 성과에 대한 실행 가능한 통찰력을 제공하도록 하세요.
- 전략적 권장 사항 : 광고 지출, 타겟팅 및 창의적인 콘텐츠 최적화를 위한 데이터 기반 제안을 받습니다.
- 자동 모니터링 : MCP 호환 LLM에 성과 지표를 추적하고 중요한 변경 사항에 대해 알림을 요청합니다.
- 예산 최적화 : 더 나은 성과를 내는 광고 세트에 예산을 재할당하기 위한 권장 사항을 받으세요.
- 크리에이티브 개선 : 광고 카피, 이미지 및 행동 촉구에 대한 피드백을 받습니다.
- 캠페인 관리 : 캠페인, 광고 세트 및 광고에 대한 변경 요청(모든 변경 사항에는 명시적 확인이 필요함)
- 크로스 플랫폼 통합 : Facebook, Instagram 및 모든 Meta 광고 플랫폼과 호환됩니다.
- 범용 LLM 지원 : Claude Desktop, Cursor, Cherry Studio 등을 포함한 모든 MCP 클라이언트와 호환
- 간단한 인증 : 안전한 OAuth 인증을 통한 간편한 설정
- 크로스 플랫폼 지원 : Windows, macOS 및 Linux에서 작동
설치
uv 사용(권장)
uv를 사용하면 별도의 설치가 필요하지 않습니다. uvx를 사용하여 meta-ads-mcp를 직접 실행할 수 있습니다.
지엑스피1
패키지를 설치하려면:
개발용(저장소를 복제한 경우):
pip 사용하기
또는 pip를 통해 meta-ads-mcp를 설치할 수 있습니다.
설치 후 다음과 같이 실행할 수 있습니다.
구성
파이프보드 인증을 사용한 빠른 시작(권장)
Meta Ads MCP를 구성하는 가장 쉬운 방법은 Pipeboard 인증을 사용하는 것입니다.
- Pipeboard.co 에 가입하고 API 토큰을 생성하세요. https://pipeboard.co 에서 무료 토큰을 받으세요.
- 환경 변수를 설정합니다.Copy
- Meta Developer 앱을 설정하지 않고도 meta-ads-mcp를 실행하세요.Copy
이 방법은 더 긴 유효 기간(60일)의 토큰, 간소화된 설정, 자동 토큰 갱신을 제공합니다.
커서 또는 Claude Desktop 사용
Claude와 통합하려면 claude_desktop_config.json 에 이것을 추가하고, Cursor와 통합하려면 ~/.cursor/mcp.json 에 이것을 추가하세요.
또는 직접 Meta 인증(자신의 Facebook 앱 사용)을 선호하는 경우:
사용 가능한 MCP 도구
mcp_meta_ads_get_ad_accounts- 사용자가 액세스할 수 있는 광고 계정 가져오기
- 입력:
access_token(선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)user_id: 메타 사용자 ID 또는 현재 사용자의 "me"limit: 반환할 최대 계정 수(기본값: 10)
- 반환: 세부 정보가 포함된 액세스 가능한 광고 계정 목록
mcp_meta_ads_get_account_info- 특정 광고 계정에 대한 자세한 정보를 얻으세요
- 입력:
access_token(선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)account_id: Meta Ads 계정 ID(형식: act_XXXXXXXXX)
- 반환: 지정된 계정에 대한 자세한 정보
mcp_meta_ads_get_campaigns- 선택적 필터링을 사용하여 Meta Ads 계정에 대한 캠페인을 받으세요
- 입력:
access_token(선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)account_id: Meta Ads 계정 ID(형식: act_XXXXXXXXX)limit: 반환할 캠페인의 최대 수(기본값: 10)status_filter: 상태별로 필터링합니다(모두 비어 있는 경우 또는 '활성', '일시 중지' 등).
- 반환: 기준과 일치하는 캠페인 목록
mcp_meta_ads_get_campaign_details- 특정 캠페인에 대한 자세한 정보를 얻으세요
- 입력:
access_token(선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)campaign_id: 메타 광고 캠페인 ID
- 반환: 지정된 캠페인에 대한 자세한 정보
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: 계정 통화(센트)로 표시된 평생 예산
- 반환: 새로운 캠페인 세부 정보 확인
mcp_meta_ads_get_adsets- 캠페인별 선택적 필터링을 통해 Meta Ads 계정에 대한 광고 세트를 가져옵니다.
- 입력:
access_token(선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)account_id: Meta Ads 계정 ID(형식: act_XXXXXXXXX)limit: 반환할 광고 세트의 최대 수(기본값: 10)campaign_id: 필터링할 선택적 캠페인 ID
- 반환: 기준과 일치하는 광고 세트 목록
mcp_meta_ads_get_adset_details- 특정 광고 세트에 대한 자세한 정보를 얻으세요
- 입력:
access_token(선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)adset_id: 메타 광고 광고 세트 ID
- 반환: 지정된 광고 세트에 대한 자세한 정보
mcp_meta_ads_get_ads- 선택적 필터링을 사용하여 Meta Ads 계정에 대한 광고를 받으세요
- 입력:
access_token(선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)account_id: Meta Ads 계정 ID(형식: act_XXXXXXXXX)limit: 반환할 광고의 최대 개수(기본값: 10)campaign_id: 필터링할 선택적 캠페인 IDadset_id: 필터링할 선택적 광고 세트 ID
- 반환: 기준과 일치하는 광고 목록
mcp_meta_ads_get_ad_details- 특정 광고에 대한 자세한 정보를 얻으세요
- 입력:
access_token(선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)ad_id: 메타 광고 광고 ID
- 반환: 지정된 광고에 대한 자세한 정보
mcp_meta_ads_get_ad_creatives
- 특정 광고에 대한 창의적인 세부 정보를 얻으세요
- 입력:
access_token(선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)ad_id: 메타 광고 광고 ID
- 반환: 텍스트, 이미지, URL을 포함한 크리에이티브 세부 정보
mcp_meta_ads_get_ad_image
- 한 단계로 메타 광고 이미지를 얻고, 다운로드하고, 시각화하세요
- 입력:
access_token(선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)ad_id: 메타 광고 광고 ID
- 반환: 직접 시각적 분석을 위해 준비된 광고 이미지
mcp_meta_ads_update_ad
- 새로운 설정으로 광고 업데이트
- 입력:
ad_id: 메타 광고 광고 IDstatus: 광고 상태(활성, 일시 중지 등)를 업데이트합니다.bid_amount: 계정 통화로 표시된 입찰 금액(USD의 경우 센트)access_token(선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
- 반환: 업데이트된 광고 세부 정보와 확인 링크가 포함된 확인
mcp_meta_ads_update_adset
- 빈도 제한을 포함한 새로운 설정으로 광고 세트 업데이트
- 입력:
adset_id: 메타 광고 광고 세트 IDfrequency_control_specs: 주파수 제어 사양 목록bid_strategy: 입찰 전략(예: 'LOWEST_COST_WITH_BID_CAP')bid_amount: 계정 통화로 표시된 입찰 금액(USD의 경우 센트)status: 광고 세트 상태(활성, 일시 중지 등)를 업데이트합니다.targeting: 타겟팅_자동화를 포함한 타겟팅 사양access_token(선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
- 반환: 업데이트된 광고 세트 세부 정보와 확인 링크가 포함된 확인
mcp_meta_ads_get_insights
- 캠페인, 광고 세트, 광고 또는 계정에 대한 성과 통찰력을 얻으세요
- 입력:
access_token(선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)object_id: 캠페인, 광고 세트, 광고 또는 계정의 IDtime_range: 통찰력에 대한 시간 범위(기본값: 최대)breakdown: 선택적 분석 차원(예: 연령, 성별, 국가)level: 집계 레벨(광고, 광고세트, 캠페인, 계정)
- 반환: 지정된 개체에 대한 성능 측정 항목
mcp_meta_ads_debug_image_download
- 이미지 다운로드 문제를 디버깅하고 자세한 진단 결과를 보고합니다.
- 입력:
access_token(선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)url: 테스트할 직접 이미지 URL (선택 사항)ad_id: 메타 광고 광고 ID(선택 사항, url이 제공되지 않은 경우 사용됨)
- 반환: 이미지 다운로드 시도에 대한 진단 정보
mcp_meta_ads_get_login_link
- Meta Ads 인증을 위한 클릭 가능한 로그인 링크를 받으세요
- 참고: 이 방법은 개인 Facebook 앱을 사용하는 경우에만 사용해야 합니다. Pipeboard 인증(권장)을 사용하는 경우 PIPEBOARD_API_TOKEN 환경 변수를 대신 설정하세요(토큰은 https://pipeboard.co 에서 얻을 수 있습니다).
- 입력:
access_token(선택 사항): Meta API 액세스 토큰(제공되지 않으면 캐시된 토큰을 사용함)
- 반환: 메타 인증을 위한 클릭 가능한 리소스 링크
메타 개발자 앱 만들기
MCP 서버를 사용하기 전에 Meta Developer 앱을 설정해야 합니다.
- 개발자를 위한 Meta 로 이동하여 새 앱을 만드세요.
- "소비자" 앱 유형을 선택하세요
- 앱 설정에서 "마케팅 API" 제품을 추가하세요.
- 앱의 OAuth 리디렉션 URI를 구성하여
http://localhost:8888/callback포함하세요. - MCP와 함께 사용할 앱 ID(클라이언트 ID)를 기록해 두세요.
입증
Meta Ads MCP는 두 가지 인증 방법을 지원합니다.
1. 파이프보드 인증 (추천 ⭐)
이 방법은 Pipeboard.co를 사용하여 Meta API 인증을 관리하고 더 오래 지속되는 토큰과 간소화된 흐름을 제공합니다.
- Pipeboard 토큰 받기 : https://pipeboard.co 에 가입하여 무료 API 토큰을 생성하세요.
- 토큰을 사용하여
PIPEBOARD_API_TOKEN환경 변수를 설정합니다.Copy - Meta Ads MCP를 정상적으로 실행하면 Pipeboard 인증을 자동으로 감지하여 사용합니다.Copy
- 명령을 처음 실행하면 Meta에서 권한을 부여할 로그인 URL이 제공됩니다.
파이프보드 인증의 이점:
- ✅ 더 오래 지속되는 토큰(60일)
- ✅ Meta Developer 앱을 구성할 필요가 없습니다.
- ✅ API 토큰만으로 더 간단한 설정
- ✅ 토큰 자동 갱신
Pipeboard 인증 흐름을 테스트하려면:
2. 직접 메타 OAuth(레거시)
데스크톱 앱용으로 설계된 기존 OAuth 2.0 흐름입니다. 이 방법은 Pipeboard 대신 자체 Facebook 앱을 사용하는 경우에만 사용해야 합니다.
인증 시 다음이 수행됩니다.
- 컴퓨터에서 로컬 콜백 서버를 시작합니다.
- Meta로 인증하려면 브라우저 창을 엽니다.
- 앱에 대한 권한을 요청합니다
- 토큰을 추출하고 안전하게 저장하기 위해 로컬 서버로 다시 리디렉션합니다.
이 방법을 사용하려면 먼저 Meta Developer 앱을 만들어야 합니다 .
문제 해결 및 로깅
Meta Ads MCP에는 문제 해결에 도움이 되는 포괄적인 로깅 시스템이 포함되어 있습니다.
로그 위치
로그 파일은 플랫폼별 위치에 저장됩니다.
- 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
일반적인 문제
인증 문제
인증 문제가 발생하는 경우:
- 권장 사항: 파이프보드 인증 사용
export PIPEBOARD_API_TOKEN=your_token설정하고 다시 시도하세요.- 이는 더 오래 지속되는 토큰과 더 나은 안정성을 제공합니다.
- Pipeboard 대시보드에서 토큰을 확인하세요
- 앱 ID 문제(직접 인증 사용 시):
(#200) Provide valid app ID와 같은 오류가 발생하는 경우 다음을 확인하세요.- Meta Developer 앱을 올바르게 설정했는지 확인하세요.
- 다음 방법 중 하나를 사용하여 올바른 앱 ID를 전달하고 있는지 확인하세요.
META_APP_ID환경 변수를 설정합니다:export META_APP_ID=your_app_id- 명령줄 인수로 전달하세요:
meta-ads-mcp --app-id your_app_id
API 오류
Meta API에서 오류가 발생하는 경우:
- 앱에 마케팅 API 제품이 추가되었는지 확인하세요.
- 사용자에게 광고 계정에 대한 적절한 권한이 있는지 확인하세요.
- 앱에 요금 제한이나 기타 제한 사항이 있는지 확인하세요.
디버깅 명령
특정 이미지 다운로드 문제의 경우 내장된 진단 도구를 사용하세요.
이를 통해 다운로드 프로세스와 잠재적인 문제에 대한 자세한 정보를 얻을 수 있습니다.
다른 앱 ID로 실행
다양한 목적으로 서로 다른 Meta App ID를 사용해야 하는 경우:
개인정보 보호 및 보안
Meta Ads MCP는 다음과 같은 보안 모범 사례를 따릅니다.
- 토큰은 플랫폼별 보안 위치에 캐시됩니다.
- Windows:
%APPDATA%\meta-ads-mcp\token_cache.json또는%APPDATA%\meta-ads-mcp\pipeboard_token_cache.json - macOS:
~/Library/Application Support/meta-ads-mcp/token_cache.json또는~/Library/Application Support/meta-ads-mcp/pipeboard_token_cache.json - Linux:
~/.config/meta-ads-mcp/token_cache.json또는~/.config/meta-ads-mcp/pipeboard_token_cache.json
- Windows:
- 각 명령에 대해 액세스 토큰을 제공할 필요는 없습니다. 캐시에서 자동으로 검색됩니다.
- 다음 환경 변수를 인수로 전달하는 대신 설정할 수 있습니다.
META_APP_ID: 귀하의 Meta 앱 ID(클라이언트 ID) - 직접 OAuth 방식용PIPEBOARD_API_TOKEN: Pipeboard 인증 방법을 위한 Pipeboard API 토큰
테스트
CLI 테스트
인증 및 기본 기능을 확인하려면 테스트 스크립트를 실행하세요.
캐시된 토큰이 있는 경우에도 새로운 인증을 강제로 실행하려면 --force-login 플래그를 사용하세요.
LLM 인터페이스 테스트
LLM 인터페이스(예: Claude)와 함께 Meta Ads MCP를 사용하는 경우:
- 직접 Meta 인증(자신의 Facebook 앱)을 사용하는 경우
mcp_meta_ads_get_login_link도구를 호출하여 인증을 테스트합니다. - Pipeboard 인증을 사용하는 경우(권장), PIPEBOARD_API_TOKEN 환경 변수가 설정되어 있는지 확인하세요(토큰은 https://pipeboard.co 에서 얻을 수 있음)
mcp_meta_ads_get_ad_accounts호출하여 계정 액세스를 확인하세요.mcp_meta_ads_get_account_info사용하여 특정 계정 세부 정보를 확인하세요.
이러한 기능은 필요한 경우 자동으로 인증을 처리하고, 필요한 경우 클릭 가능한 로그인 링크를 제공합니다.
문제 해결
인증 문제
인증 문제가 발생하는 경우:
- LLM 인터페이스를 사용하는 경우:
- 직접 Meta 인증(자신의 Facebook 앱)을 사용하는 경우
mcp_meta_ads_get_login_link도구를 사용하여 새 인증 링크를 생성하세요. - Pipeboard 인증을 사용하는 경우(권장), PIPEBOARD_API_TOKEN 환경 변수가 설정되어 있는지 확인하세요(토큰은 https://pipeboard.co 에서 얻을 수 있음)
- 링크를 클릭하고 브라우저에서 권한 부여 흐름을 완료하세요.
- 콜백 서버가 제대로 실행되고 있는지 확인하세요(도구에서 이를 보고합니다)
- 직접 Meta 인증(자신의 Facebook 앱)을 사용하는 경우
- Pipeboard 인증을 사용하는 경우:
PIPEBOARD_API_TOKEN이 올바르게 설정되었는지 확인하세요(토큰은 https://pipeboard.co 에서 얻을 수 있음)- 제공된 로그인 URL을 방문하여 권한 부여 프로세스를 완료해야 하는지 확인하세요.
- 새로운 로그인을 강제로 시도해 보세요:
python test_pipeboard_auth.py --force-login
- 직접 Meta OAuth를 사용하는 경우:
--force-login사용하여 새 토큰을 받으세요:uvx meta-ads-mcp --login --app-id YOUR_APP_ID --force-login- 터미널에 브라우저 창을 열 수 있는 권한이 있는지 확인하세요.
API 오류
Meta API에서 오류가 발생하는 경우:
- 앱에 마케팅 API 제품이 추가되었는지 확인하세요.
- 사용자에게 광고 계정에 대한 적절한 권한이 있는지 확인하세요.
- 앱에 요금 제한이나 기타 제한 사항이 있는지 확인하세요.
버전 관리
패키지의 현재 버전을 확인할 수 있습니다.
You must be authenticated.
AI 모델이 메타 광고 캠페인에 액세스하고 이를 분석하고 관리할 수 있도록 하는 모델 컨텍스트 프로토콜 서버로, LLM이 성과 데이터를 검색하고, 광고 크리에이티브를 시각화하고, Facebook 및 Instagram 플랫폼에 대한 전략적 통찰력을 제공할 수 있도록 지원합니다.