PropellerAds MCP Server

Democratizing Programmatic Advertising with AI

Let AI assistants like Claude manage your advertising campaigns on PropellerAds automatically.

Quick Start • Available Tools • Usage Examples • MCP Configuration

What is this?

PropellerAds MCP is a Model Context Protocol server that connects AI assistants (Claude, and any MCP-compatible client) directly to the PropellerAds advertising platform API. Instead of manually logging into dashboards, pulling reports, and clicking through settings, you simply talk to your AI assistant in plain English and it handles everything for you.

Create campaigns, analyze performance, blacklist underperforming zones, find scaling opportunities, compare time periods -- all through natural conversation.

Built for:

• Media Buyers and Performance Marketers

• iGaming and App Install Affiliates

• Growth Hackers and Digital Agencies

• Anyone running PropellerAds campaigns who wants to work faster

Features

• Full Campaign Lifecycle -- Create, update, start, stop, and clone campaigns without leaving your chat

• Real-Time Performance Analytics -- Impressions, clicks, conversions, CTR, CVR, CPC, CPA, and ROI calculated automatically

• Period-over-Period Comparison -- Compare any two date ranges side by side with trend indicators

• Zone-Level Optimization -- Find underperforming zones wasting budget and top zones worth whitelisting

• Automated Blacklisting -- One command to identify and blacklist bad zones (with dry-run safety mode)

• Scaling Intelligence -- Automatically find campaigns with strong ROI and conversion volume ready to scale

• Creative Performance Breakdown -- See which creatives drive results and which need replacement

• Secure by Design -- API token stored in environment variables, never exposed in conversation

• Dry Run Safety -- Destructive operations default to preview mode before executing

Available Tools

Campaign Management

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

Statistics & Analytics

Common optional params: date_from, date_to (YYYY-MM-DD, defaults to 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 Account with API access

   • Minimum requirement: $1,000 total spend or deposit

   • 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

Option 1: Install from PyPI (Recommended)

pip install propellerads-mcp

Option 2: Install from source

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

Set your API token

Create a .env file in the project root or export the environment variable:

export PROPELLERADS_API_TOKEN="your_api_token_here"

Usage Examples

Campaign Management

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

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

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 via 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 & Permissions

Contributing

Contributions are welcome! Here is how you can help:

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 Naftanaila -- Media Buyer & AI Automation Specialist

Building tools that bridge the gap between AI and programmatic advertising. Focused on making adtech accessible, automated, and intelligent.

License

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

PropellerAds MCP -- Open source. Built for the programmatic advertising community.