Skip to main content
Glama
PropellerAds MCP Server

PropellerAds MCP Server

by JanNafta

PropellerAds MCP 서버

AI를 통한 프로그래매틱 광고의 대중화

Python 3.10+ MCP License: MIT Status GitHub Stars GitHub Forks

Claude와 같은 AI 어시스턴트가 PropellerAds의 광고 캠페인을 자동으로 관리하게 하세요.

빠른 시작 • 사용 가능한 도구 • 사용 예시 • MCP 설정


이것은 무엇인가요?

PropellerAds MCP는 AI 어시스턴트(Claude 및 모든 MCP 호환 클라이언트)를 PropellerAds 광고 플랫폼 API에 직접 연결하는 모델 컨텍스트 프로토콜(Model Context Protocol) 서버입니다. 대시보드에 수동으로 로그인하고, 보고서를 추출하고, 설정을 클릭하는 대신, AI 어시스턴트에게 평범한 언어로 말하기만 하면 모든 것을 처리해 줍니다.

자연스러운 대화를 통해 캠페인 생성, 성과 분석, 실적이 저조한 존(zone) 블랙리스트 등록, 확장 기회 탐색, 기간 비교 등을 수행하세요.

대상:

  • 미디어 바이어 및 퍼포먼스 마케터

  • iGaming 및 앱 설치 제휴 마케터

  • 그로스 해커 및 디지털 에이전시

  • 더 빠르게 작업하고자 하는 PropellerAds 캠페인 운영자


Related MCP server: Google Ad Manager MCP Server

주요 기능

  • 전체 캠페인 수명 주기 -- 채팅을 떠나지 않고 캠페인 생성, 업데이트, 시작, 중지 및 복제

  • 실시간 성과 분석 -- 노출, 클릭, 전환, CTR, CVR, CPC, CPA 및 ROI 자동 계산

  • 기간별 비교 -- 추세 지표와 함께 두 기간을 나란히 비교

  • 존(Zone) 단위 최적화 -- 예산을 낭비하는 저성과 존을 찾고 화이트리스트에 추가할 가치가 있는 상위 존 식별

  • 자동 블랙리스트 등록 -- 불량 존을 식별하고 블랙리스트에 등록하는 단일 명령(드라이런 안전 모드 포함)

  • 확장 지능 -- ROI와 전환율이 높아 확장이 가능한 캠페인을 자동으로 탐색

  • 크리에이티브 성과 분석 -- 어떤 크리에이티브가 성과를 내고 어떤 것을 교체해야 하는지 확인

  • 보안 설계 -- API 토큰은 환경 변수에 저장되며 대화 중에 노출되지 않음

  • 드라이런 안전성 -- 파괴적인 작업은 실행 전 미리보기 모드를 기본값으로 설정


사용 가능한 도구

캠페인 관리

도구

설명

필수 매개변수

list_campaigns

선택적 필터를 사용하여 모든 캠페인 나열

--

get_campaign_details

전체 캠페인 정보(타겟팅, 크리에이티브, 설정) 가져오기

campaign_id

create_campaign

새 광고 캠페인 생성

name, ad_format, countries, daily_budget, bid, target_url

update_campaign

캠페인 설정 수정(예산, 입찰가, 이름, 상태)

campaign_id

start_campaigns

일시 중지된 하나 이상의 캠페인 활성화

campaign_ids

stop_campaigns

활성 상태인 하나 이상의 캠페인 일시 중지

campaign_ids

clone_campaign

기존 캠페인 복제

campaign_id

list_campaigns용 필터: status(active/paused/pending/rejected), ad_format(push/onclick/interstitial/in-page-push), name(부분 일치)

통계 및 분석

도구

설명

필수 매개변수

get_performance_report

계산된 지표(CTR, CVR, CPC, CPA, ROI)가 포함된 상세 통계

--

get_campaign_performance

특정 캠페인에 대한 성과 요약

campaign_id

compare_periods

변경 지표와 함께 두 기간 비교

period1_from, period1_to, period2_from, period2_to

get_zone_performance

존/게재 위치(Zone) 수준 분석, 정렬 가능

--

get_creative_performance

크리에이티브 수준 성과 분석

--

일반적인 선택적 매개변수: date_from, date_to(YYYY-MM-DD, 기본값은 최근 7일), campaign_id, group_by(date/campaign/zone/country/creative/device_type/browser/os)

최적화

도구

설명

필수 매개변수

find_underperforming_zones

전환 없이 비용만 발생하는 존 탐색(블랙리스트 후보)

campaign_id

find_top_zones

성과가 가장 좋은 존 탐색(화이트리스트 후보)

campaign_id

find_scaling_opportunities

확장 준비가 된 캠페인 탐색(높은 ROI + 볼륨)

--

auto_blacklist_zones

불량 존을 한 번에 찾아 블랙리스트 등록(기본값은 드라이런)

campaign_id

타겟팅

도구

설명

필수 매개변수

add_to_whitelist

캠페인의 화이트리스트에 존 추가

campaign_id, zone_ids

add_to_blacklist

캠페인의 블랙리스트에 존 추가

campaign_id, zone_ids

계정

도구

설명

필수 매개변수

get_balance

현재 계정 잔액 확인

--

get_available_countries

타겟팅 가능한 모든 국가 나열

--

get_ad_formats

사용 가능한 광고 형식 나열(push, onclick 등)

--


기술 스택

구성 요소

기술

런타임

Python 3.10+

프로토콜

Model Context Protocol (MCP) 1.0

HTTP 클라이언트

httpx

유효성 검사

Pydantic v2

API

PropellerAds SSP API v5

빌드 시스템

Hatchling

전송

stdio (표준 MCP 전송)


빠른 시작

사전 요구 사항

  1. PropellerAds 계정 (API 액세스 권한 필요)

  2. Python 3.10+

  3. Claude Desktop 또는 Claude Code (또는 MCP 호환 클라이언트)

설치

옵션 1: PyPI에서 설치 (권장)

pip install propellerads-mcp

옵션 2: 소스에서 설치

git clone https://github.com/JanNafta/propellerads-mcp.git
cd propellerads-mcp
pip install -e .

API 토큰 설정

프로젝트 루트에 .env 파일을 생성하거나 환경 변수를 내보내세요:

export PROPELLERADS_API_TOKEN="your_api_token_here"

사용 예시

캠페인 관리

"Show me all my active campaigns sorted by ROI"

"Create a push campaign for gaming offers in Brazil with $100 daily budget"

"Pause all campaigns with negative ROI in the last 7 days"

"Clone my best performing campaign to Mexico, Colombia, and Peru"

성과 분석

"What's my campaign performance for the last week?"

"Compare this week's performance vs last week"

"Show me the top 10 zones by conversions for campaign 12345"

"Which creatives have CTR below 0.5%?"

최적화 워크플로우

"Find all zones spending over $50 without conversions and blacklist them"

"Show me campaigns ready for scaling -- ROI above 50% with at least 10 conversions"

"Find top performing zones for my dating campaigns and add them to a whitelist"

일일 최적화 루틴

1. "Show me yesterday's performance for all campaigns"
2. "Find and blacklist underperforming zones across all campaigns"
3. "Which campaigns are ready for scaling?"
4. "Increase budget by 50% for profitable campaigns"

MCP 설정

Claude Desktop

Claude Desktop 설정 파일에 추가하세요:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "propellerads": {
      "command": "python",
      "args": ["-m", "propellerads_mcp"],
      "env": {
        "PROPELLERADS_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

설정을 저장한 후 Claude Desktop을 다시 시작하세요.

Claude Code

CLI를 사용하여 Claude Code에 MCP 서버를 추가하세요:

claude mcp add propellerads -- python -m propellerads_mcp

Claude Code를 실행하기 전에 셸 환경에 PROPELLERADS_API_TOKEN이 설정되어 있는지 확인하세요.

기타 MCP 클라이언트

이 서버는 표준 MCP 통신 방식인 stdio 전송을 사용합니다. 모든 MCP 호환 클라이언트는 프로세스를 생성하여 연결할 수 있습니다:

python -m propellerads_mcp

서버는 환경에서 PROPELLERADS_API_TOKEN을 읽습니다. MCP 클라이언트의 env 설정을 통해 전달하거나 셸에서 설정하세요.


프로젝트 구조

propellerads-mcp/
├── src/
│   └── propellerads_mcp/
│       ├── __init__.py       # Package init, version, exports
│       ├── __main__.py       # Module entry point (python -m)
│       ├── client.py         # PropellerAds API client (httpx-based)
│       └── server.py         # MCP server, tool definitions & handlers
├── .env.example              # Environment variable template
├── .gitignore
├── LICENSE                   # MIT License
├── pyproject.toml            # Build config, dependencies, metadata
└── README.md

보안 및 권한

측면

세부 정보

인증

환경 변수를 통한 Bearer 토큰 (하드코딩 금지)

읽기 작업

추가 확인 없이 실행

쓰기 작업

명시적인 사용자 의도 필요 (생성, 업데이트, 시작, 중지, 블랙리스트)

자동 블랙리스트

기본값 dry_run: true -- 실행 전 미리보기

속도 제한

PropellerAds API 속도 제한 준수

데이터 저장

서버는 상태 비저장(stateless) 방식이며 로컬에 데이터를 저장하지 않음


기여하기

기여를 환영합니다! 다음과 같이 도울 수 있습니다:

  1. 포크(Fork) 저장소

  2. 기능 브랜치 생성 (git checkout -b feature/my-feature)

  3. 변경 사항 커밋 (git commit -m "Add my feature")

  4. 브랜치 푸시 (git push origin feature/my-feature)

  5. 풀 리퀘스트(Pull Request) 열기

버그 및 기능 요청은 이슈를 열어주세요.


작성자

Jan Naftanaila -- 미디어 바이어 & AI 자동화 전문가

AI와 프로그래매틱 광고 사이의 격차를 해소하는 도구를 구축합니다. 애드테크를 접근 가능하고 자동화되며 지능적으로 만드는 데 집중하고 있습니다.

LinkedIn Website GitHub


라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.


PropellerAds MCP -- 오픈 소스. 프로그래매틱 광고 커뮤니티를 위해 구축되었습니다.

Available Tools

21 tools
add_to_blacklistC

Add zones to campaign blacklist.

Inputs: campaign_id (required), zone_ids (required).

add_to_whitelistC

Add zones to campaign whitelist.

Inputs: campaign_id (required), zone_ids (required).

auto_blacklist_zonesC

Automatically find and blacklist underperforming zones for a campaign.

Inputs: campaign_id (required), min_spend, max_conversions, date_from, +2 more.

clone_campaignC

Create a copy of an existing campaign.

Inputs: campaign_id (required), new_name.

compare_periodsC

Compare performance between two time periods.

Inputs: period1_from (required), period1_to (required), period2_from (required), period2_to (required), +1 more.

create_campaignC

Create a new advertising campaign with specified settings.

Inputs: name (required), ad_format (required), countries (required), daily_budget (required), +4 more.

find_scaling_opportunitiesC

Find campaigns ready for scaling based on ROI and conversion volume.

Inputs: min_roi, min_conversions, date_from, date_to.

find_top_zonesC

Find best performing zones. Useful for whitelist candidates.

Inputs: campaign_id (required), min_conversions, min_roi, limit, +2 more.

find_underperforming_zonesB

Find zones that are spending money but not converting. Useful for blacklist candidates.

Inputs: campaign_id (required), min_spend, max_conversions, date_from, +1 more.

get_ad_formatsB

Get list of available ad formats.

Inputs: no named parameters.

get_available_countriesB

Get list of available countries for targeting.

Inputs: no named parameters.

get_balanceB

Get current account balance.

Inputs: no named parameters.

get_campaign_detailsB

Get complete details for a specific campaign including targeting, creatives, and settings.

Inputs: campaign_id (required).

get_campaign_performanceC

Get performance summary for a specific campaign with calculated metrics and insights.

Inputs: campaign_id (required), date_from, date_to.

get_creative_performanceC

Get performance statistics for creatives.

Inputs: campaign_id, date_from, date_to.

get_performance_reportC

Get detailed performance statistics with metrics like impressions, clicks, conversions, spend, CTR, CVR, CPC, CPA, and ROI.

Inputs: date_from, date_to, group_by, campaign_id.

get_zone_performanceB

Get performance statistics grouped by zone/placement. Useful for whitelist/blacklist optimization.

Inputs: campaign_id, date_from, date_to, limit, +1 more.

list_campaignsB

List all campaigns with optional filters. Returns campaign ID, name, status, ad format, and basic metrics.

Inputs: status, ad_format, name.

start_campaignsC

Activate/start one or more campaigns.

Inputs: campaign_ids (required).

stop_campaignsC

Pause/stop one or more campaigns.

Inputs: campaign_ids (required).

update_campaignC

Update campaign settings like budget, bid, targeting, or status.

Inputs: campaign_id (required), name, daily_budget, total_budget, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 21 tools

    Disambiguation4/5

    Most tools have distinct purposes with clear boundaries, such as campaign management (create, clone, update, start, stop), performance analysis (get_campaign_performance, get_performance_report), and zone optimization (find_top_zones, find_underperforming_zones). However, some overlap exists between get_campaign_performance and get_performance_report, which could cause confusion about which to use for campaign-specific metrics.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern throughout, such as create_campaign, list_campaigns, get_balance, and find_top_zones. All tools use snake_case without deviation, making them predictable and easy to parse for agents.

    Tool Count4/5

    With 21 tools, the count is slightly high but reasonable for the comprehensive advertising campaign management domain. It covers campaign lifecycle, performance reporting, and optimization tasks, though it borders on being heavy compared to typical well-scoped servers (3-15 tools).

    Completeness5/5

    The toolset provides complete coverage for the advertising campaign domain, including CRUD operations (create, list, get, update, clone), lifecycle management (start, stop), performance analysis (various get and compare tools), and optimization features (blacklist/whitelist, scaling, zone analysis). No obvious gaps are present, enabling agents to handle end-to-end workflows.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to manage TikTok advertising campaigns through the TikTok Ads API. Supports campaign creation, performance analytics, audience management, creative operations, and custom reporting through natural language interactions.
      54
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to manage Google Ad Manager campaigns, line items, creatives, and advertisers through natural language, automating ad operations that normally require countless clicks through the UI.
      35
      58 PyPI
      20
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables comprehensive management of Google Ads campaigns through natural language, including campaign creation, ad group management, keyword operations, Performance Max campaigns, conversion tracking, and performance insights with support for multiple accounts.
      3
      -
    • A
      license
      C
      quality
      C
      maintenance
      Enables managing your entire AdButler advertising account from any AI assistant, exposing over 600 tools covering the full AdButler v2 API for display ads, video, targeting, reporting, programmatic, and more, plus pre-built workflow prompts.
      100
      150 npm
      1
      MIT