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

Related MCP server: Google Ad Manager MCP Server

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

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

Statistics and Analytics

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

Targeting

Account

Tech Stack

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

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.