propellerads-mcp

PropellerAds MCP Server

Run, read and optimize PropellerAds campaigns from your AI assistant

Connect Claude (or any MCP client) to the PropellerAds advertiser API and manage push, onclick and in-page push campaigns in plain English.

Quick Start · Available Tools · Usage Examples · MCP Configuration

---

What is this?

PropellerAds MCP is a Model Context Protocol server that connects AI assistants to the PropellerAds SSP API v5. Instead of logging into the dashboard, exporting reports and clicking through zone lists, you ask your assistant and it calls the API for you.

Pull performance reports, compare two periods, find zones that spend without converting, blacklist them, clone a profitable campaign into new countries. All from one conversation.

Built for:

• Media buyers and performance marketers running push, pop and in-page push traffic
• Advertisers and affiliates promoting apps, ecommerce, lead generation and other offers
• Agencies and in-house UA teams who want reports and zone cleanup without the manual exports
• Anyone running PropellerAds campaigns who wants to work faster

---

Features

• Full campaign lifecycle: create, update, start, stop and clone campaigns without leaving the chat
• Performance analytics: impressions, clicks, conversions, spend, CTR, CVR, CPC, CPA and ROI on every report
• Period comparison: two date ranges side by side, with the percentage change for each metric
• Zone-level optimization: zones that spend without converting, and top zones worth whitelisting
• Automated blacklisting: one call finds and blacklists bad zones, in preview mode by default
• Scaling candidates: campaigns above your ROI and conversion thresholds (defaults: 50% ROI, 10 conversions)
• Creative breakdown: which creatives drive results and which need replacing
• Token stays out of the chat: the API token is read from an environment variable

About ROI and CPA. These numbers are only as good as the conversions and payouts you send back to PropellerAds. Without postback tracking, conversions and revenue stay at zero and ROI reads -100%. Set up the postback (or your tracker's integration) before you let the assistant blacklist or scale anything.

---

Available Tools

21 tools in five groups.

Campaign Management

Tool	Description	Required Parameters
list_campaigns	List all campaigns with optional filters	None
get_campaign_details	Get complete campaign info (targeting, creatives, settings)	campaign_id
create_campaign	Create a new advertising campaign	name, ad_format, countries, daily_budget, bid, target_url
update_campaign	Change name, daily or total budget, bid or status	campaign_id
start_campaigns	Activate one or more paused campaigns	campaign_ids
stop_campaigns	Pause one or more active campaigns	campaign_ids
clone_campaign	Duplicate an existing campaign	campaign_id

Filters for list_campaigns: status (active, paused, pending, rejected), ad_format (push, onclick, interstitial, in-page-push), name (partial match)

Statistics and Analytics

Tool	Description	Required Parameters
get_performance_report	Detailed stats with computed metrics (CTR, CVR, CPC, CPA, ROI)	None
get_campaign_performance	Performance summary for a specific campaign	campaign_id
compare_periods	Compare two time periods with the change for each metric	period1_from, period1_to, period2_from, period2_to
get_zone_performance	Zone (placement) level analytics, sortable	None
get_creative_performance	Creative level performance breakdown	None

Common optional params: date_from, date_to (YYYY-MM-DD, defaults to the last 7 days), campaign_id, group_by (date, campaign, zone, country, creative, device_type, browser, os)

Optimization

Tool	Description	Required Parameters
find_underperforming_zones	Zones spending money without converting (blacklist candidates)	campaign_id
find_top_zones	Best performing zones (whitelist candidates)	campaign_id
find_scaling_opportunities	Campaigns ready to scale (ROI and volume above your thresholds)	None
auto_blacklist_zones	Find and blacklist bad zones in one step (dry run by default)	campaign_id

Targeting

Tool	Description	Required Parameters
add_to_whitelist	Add zones to a campaign's whitelist	campaign_id, zone_ids
add_to_blacklist	Add zones to a campaign's blacklist	campaign_id, zone_ids

Account

Tool	Description	Required Parameters
get_balance	Check current account balance	None
get_available_countries	List all countries available for targeting	None
get_ad_formats	List available ad formats (push, onclick, etc.)	None

---

Tech Stack

Component	Technology
Runtime	Python 3.10+
Protocol	Model Context Protocol, Python SDK mcp 1.x
HTTP Client	httpx
Validation	Pydantic v2
API	PropellerAds SSP API v5
Build System	Hatchling
Transport	stdio (standard MCP transport)

---

Quick Start

Prerequisites

1. PropellerAds advertiser account with API access
   • PropellerAds opens the API to accounts with at least $1,000 in total spend or deposit. Check your account if you are close to that line.
   • Get your API token: https://ssp.propellerads.com/#/app/profile
2. Python 3.10+
3. Claude Desktop or Claude Code (or any MCP-compatible client)

Installation

The package is not on PyPI. Install it straight from GitHub:

pip install "git+https://github.com/JanNafta/propellerads-mcp.git"

Or from source, if you want to change the code:

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

Both install the propellerads-mcp command and the propellerads_mcp module. The server targets version 1.x of the MCP Python SDK, and the dependency is pinned below 2.0 for that reason.

Set your API token

Export the environment variable in the shell or in your MCP client config:

export PROPELLERADS_API_TOKEN="your_api_token_here"

With a source install you can also copy .env.example to .env in the project root. The server loads it on start.

---

Usage Examples

Campaign Management

"Show me all my active campaigns sorted by ROI"

"Create a push campaign for my app install offer in Brazil with a $100 daily budget"

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

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

Performance Analysis

"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%?"

Optimization Workflows

"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 lead gen campaigns and add them to a whitelist"

Daily Optimization Routine

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 Configuration

Claude Desktop

Add to your Claude Desktop config file:

• 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"
      }
    }
  }
}

If you installed into a virtualenv, put the full path to that environment's python in command. Restart Claude Desktop after saving the configuration.

Claude Code

Add the MCP server to Claude Code using the CLI:

claude mcp add propellerads -- python -m propellerads_mcp

Make sure PROPELLERADS_API_TOKEN is set in your shell environment before launching Claude Code.

Other MCP Clients

This server uses stdio transport, the standard MCP communication method. Any MCP-compatible client can connect by spawning the process:

python -m propellerads_mcp

The server reads PROPELLERADS_API_TOKEN from the environment. Pass it through the env configuration of your MCP client or set it in your shell.

---

Project Structure

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

---

Security and Permissions

Aspect	Details
Authentication	Bearer token from PROPELLERADS_API_TOKEN, never hardcoded
Read tools	Only read data from your account
Write tools	Create, update, start, stop, clone, whitelist and blacklist change your live account as soon as the client calls them. Keep tool approval switched on in your MCP client
Auto-blacklist	dry_run defaults to true, so the first call only previews the zones
Rate limits	The server does not throttle or retry. Long loops of calls can hit the PropellerAds API limits
No data storage	The server is stateless. Nothing is written to disk

---

Contributing

Contributions are welcome:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m "Add my feature")
4. Push to your branch (git push origin feature/my-feature)
5. Open a Pull Request

For bugs and feature requests, please open an issue.

---

Author

Jan Nafta, performance marketer and user acquisition consultant. Founder of Digital Nafta.

I buy paid traffic on Meta, Google, TikTok, Apple Ads, programmatic DSPs and ad networks like PropellerAds and ExoClick, and I build the tools I wish I had. This server is one of them.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

Independent open source project. Not affiliated with or endorsed by PropellerAds.

---

PropellerAds MCP: open source tooling for media buyers.