PropellerAds MCP Server
by JanNafta
README.md
<div align="center">
# PropellerAds MCP Server
**Run, read and optimize PropellerAds campaigns from your AI assistant**
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
[](https://opensource.org/licenses/MIT)
[](https://github.com/JanNafta/propellerads-mcp/stargazers)
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](#quick-start) · [Available Tools](#available-tools) · [Usage Examples](#usage-examples) · [MCP Configuration](#mcp-configuration)
</div>
---
## What is this?
PropellerAds MCP is a **Model Context Protocol server** that connects AI assistants to the [PropellerAds](https://propellerads.com) 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](https://modelcontextprotocol.io), Python SDK `mcp` 1.x |
| HTTP Client | [httpx](https://www.python-httpx.org/) |
| Validation | [Pydantic](https://docs.pydantic.dev/) v2 |
| API | [PropellerAds SSP API v5](https://ssp-api.propellerads.com/v5) |
| Build System | [Hatchling](https://hatch.pypa.io/) |
| 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:
```bash
pip install "git+https://github.com/JanNafta/propellerads-mcp.git"
```
Or from source, if you want to change the code:
```bash
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:
```bash
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`
```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:
```bash
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:
```bash
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](https://github.com/JanNafta/propellerads-mcp/issues).
---
## Author
**Jan Nafta**, performance marketer and user acquisition consultant. Founder of [Digital Nafta](https://digitalnafta.com).
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.
[](https://www.linkedin.com/in/jannafta-programmatic-performance-dsp-ssp-rtb/)
[](https://jannafta.com)
[](https://digitalnafta.com)
[](https://github.com/JanNafta)
---
## License
This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.
Independent open source project. Not affiliated with or endorsed by PropellerAds.
---
<div align="center">
**[PropellerAds MCP](https://github.com/JanNafta/propellerads-mcp)**: open source tooling for media buyers.
</div>
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
ActivityMaintained
ResponsivenessNo issues