PropellerAds MCP Server
PropellerAds MCP 服务器
用 AI 普及程序化广告
让像 Claude 这样的 AI 助手自动管理您在 PropellerAds 上的广告系列。
这是什么?
PropellerAds MCP 是一个 模型上下文协议 (Model Context Protocol) 服务器,它将 AI 助手(Claude 以及任何兼容 MCP 的客户端)直接连接到 PropellerAds 广告平台 API。无需手动登录仪表板、提取报告和点击设置,您只需用简单的英语与您的 AI 助手交谈,它就会为您处理一切。
创建广告系列、分析性能、屏蔽表现不佳的广告位、寻找扩展机会、比较时间段——所有这些都可以通过自然对话完成。
专为以下人群打造:
媒体买家和效果营销人员
iGaming 和应用安装联盟营销人员
增长黑客和数字营销代理机构
任何希望提高工作效率的 PropellerAds 广告系列运营者
Related MCP server: Google Ad Manager MCP Server
功能特性
完整的广告系列生命周期 -- 无需离开聊天界面即可创建、更新、启动、停止和克隆广告系列
实时性能分析 -- 自动计算展示量、点击量、转化量、CTR、CVR、CPC、CPA 和 ROI
周期对比 -- 并排比较任意两个日期范围,并带有趋势指标
广告位级优化 -- 找出浪费预算的表现不佳的广告位,以及值得加入白名单的顶级广告位
自动屏蔽 -- 一条指令即可识别并屏蔽不良广告位(带有试运行安全模式)
智能扩展 -- 自动寻找具有高 ROI 和转化量且准备好扩展的广告系列
创意性能细分 -- 查看哪些创意能带来效果,哪些需要更换
安全设计 -- API 令牌存储在环境变量中,绝不会在对话中泄露
试运行安全机制 -- 破坏性操作在执行前默认为预览模式
可用工具
广告系列管理
工具 | 描述 | 必需参数 |
| 列出所有广告系列(可选过滤器) | -- |
| 获取完整的广告系列信息(定向、创意、设置) |
|
| 创建新的广告系列 |
|
| 修改广告系列设置(预算、出价、名称、状态) |
|
| 激活一个或多个已暂停的广告系列 |
|
| 暂停一个或多个活动的广告系列 |
|
| 复制现有的广告系列 |
|
list_campaigns 的过滤器: status (active/paused/pending/rejected), ad_format (push/onclick/interstitial/in-page-push), name (部分匹配)
统计与分析
工具 | 描述 | 必需参数 |
| 包含计算指标(CTR, CVR, CPC, CPA, ROI)的详细统计数据 | -- |
| 特定广告系列的性能摘要 |
|
| 比较两个时间段并显示变化指标 |
|
| 可排序的广告位/版位级分析 | -- |
| 创意级性能细分 | -- |
常用可选参数: date_from, date_to (YYYY-MM-DD,默认为过去 7 天), campaign_id, group_by (date/campaign/zone/country/creative/device_type/browser/os)
优化
工具 | 描述 | 必需参数 |
| 查找未转化但正在消耗预算的广告位(屏蔽候选) |
|
| 查找表现最好的广告位(白名单候选) |
|
| 查找准备好扩展的广告系列(高 ROI + 高流量) | -- |
| 一步查找并屏蔽不良广告位(默认试运行) |
|
定向
工具 | 描述 | 必需参数 |
| 将广告位添加到广告系列的白名单 |
|
| 将广告位添加到广告系列的黑名单 |
|
账户
工具 | 描述 | 必需参数 |
| 查看当前账户余额 | -- |
| 列出所有可用于定向的国家/地区 | -- |
| 列出可用的广告格式(push, onclick 等) | -- |
技术栈
组件 | 技术 |
运行时 | Python 3.10+ |
协议 | |
HTTP 客户端 | |
验证 | Pydantic v2 |
API | |
构建系统 | |
传输 | stdio (标准 MCP 传输) |
快速开始
先决条件
PropellerAds 账户(需具备 API 访问权限)
最低要求:总支出或充值达到 $1,000
获取您的 API 令牌:https://ssp.propellerads.com/#/app/profile
Python 3.10+
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.jsonWindows:
%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 将 MCP 服务器添加到 Claude Code:
claude mcp add propellerads -- python -m propellerads_mcp在启动 Claude Code 之前,请确保在 shell 环境中设置了 PROPELLERADS_API_TOKEN。
其他 MCP 客户端
此服务器使用 stdio 传输,这是标准的 MCP 通信方法。任何兼容 MCP 的客户端都可以通过启动该进程进行连接:
python -m propellerads_mcp服务器从环境中读取 PROPELLERADS_API_TOKEN。请通过 MCP 客户端的 env 配置传递它,或在您的 shell 中设置它。
项目结构
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 令牌(从不硬编码) |
读取操作 | 无需额外确认即可执行 |
写入操作 | 需要明确的用户意图(创建、更新、启动、停止、屏蔽) |
自动屏蔽 | 默认为 |
速率限制 | 遵守 PropellerAds API 速率限制 |
数据存储 | 服务器是无状态的;本地不持久化任何数据 |
贡献
欢迎贡献!您可以这样提供帮助:
Fork 本仓库
创建 功能分支 (
git checkout -b feature/my-feature)提交 您的更改 (
git commit -m "Add my feature")推送 到您的分支 (
git push origin feature/my-feature)发起 Pull Request
对于错误报告和功能请求,请 提交 issue。
作者
Jan Naftanaila -- 媒体买家与 AI 自动化专家
致力于构建连接 AI 与程序化广告的工具。专注于让广告技术变得易于访问、自动化且智能化。
许可证
本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。
PropellerAds MCP -- 开源。为程序化广告社区打造。
Available Tools
21 toolsadd_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
Scored across 21 tools
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.
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.
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).
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
Related MCP Connectors
Build, edit and sync Google, Microsoft, Reddit and Meta ad campaigns from your assistant.
Manage and optimize your ads on Meta, Google, TikTok, X, ChatGPT Ads, Reddit and LinkedIn from chat.
Manage Google, Meta, TikTok, Microsoft, Pinterest, Amazon, LinkedIn & Reddit ads from your AI
Run Google Ads and Meta Ads from ChatGPT or Claude: audit wasted spend, create and manage campaigns.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables 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.54MIT
- AlicenseAqualityDmaintenanceEnables 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.3558 PyPI20MIT
- FlicenseNot gradedqualityDmaintenanceEnables 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-

AdButler MCP Serverofficial
AlicenseCqualityCmaintenanceEnables 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.100150 npm1MIT