# Snapchat Ads MCP Server

A free, open-source Model Context Protocol (MCP) server that connects Claude AI directly to your Snapchat Ads account — enabling live campaign analysis and real actions without leaving your chat.

## What It Does

| Capability | Tools |
|---|---|
| **Analyze** | Account report, campaign stats, ad squad breakdown, creative performance |
| **Act** | Pause/activate campaigns & ad squads, update budgets, rename campaigns |
| **Metrics** | ROAS, CPA, CTR, eCPM, swipe-up rate, video views, avg screen time |

No CSV exports. No manual copy-paste. Just ask Claude in plain language.

---

## Quick Demo

```
"Give me a performance report for last 7 days"
"Pause all underperforming ad squads"
"What's my ROAS across all active campaigns?"
"Update daily budget for campaign X to $100"
```

---

## Requirements

- Python 3.10+
- Snapchat Business Account
- Snapchat Marketing API credentials (free — see setup below)

---

## Install

### Option A — PyPI (Recommended, 1-click)

```bash
pip install snapchat-ads-mcp
```

Or run directly without installing (requires `uv`):

```bash
uvx snapchat-ads-mcp
```

Claude Desktop config with PyPI install:

```json
{
  "mcpServers": {
    "snapchat-ads": {
      "command": "uvx",
      "args": ["snapchat-ads-mcp"],
      "env": {
        "SNAPCHAT_CLIENT_ID": "your_client_id",
        "SNAPCHAT_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

### Option B — Manual Setup

```bash
git clone https://github.com/saadsh0/snapchat-ads-mcp
cd snapchat-ads-mcp
pip install -r requirements.txt
```

---

## Setup

### Step 1 — Clone & Install

```bash
git clone https://github.com/saadsh0/snapchat-ads-mcp
cd snapchat-ads-mcp
pip install -r requirements.txt
```

### Step 2 — Get Snapchat API Credentials (Free)

1. Go to [business.snapchat.com](https://business.snapchat.com)
2. Navigate to **Business Details → OAuth Apps → New App**
3. Set redirect URI to `https://example.com`
4. Copy your **Client ID** and **Client Secret**

> ⚠️ Use **Business Manager** to create the app — NOT the Developer Portal

### Step 3 — Set Environment Variables

```bash
export SNAPCHAT_CLIENT_ID=your_client_id
export SNAPCHAT_CLIENT_SECRET=your_client_secret
```

Or create a `.env` file (see `.env.example`).

### Step 4 — Authorize Your Account (One Time)

```bash
python auth_setup.py
```

This opens Snapchat in your browser → you click Allow → you paste the redirect URL → your org is auto-detected and locked into config → tokens saved. Never needed again.

### Step 5 — Connect to Claude Desktop

Add this to your `claude_desktop_config.json`:

**Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "snapchat-ads": {
      "command": "python3",
      "args": ["/full/path/to/snapchat-ads-mcp/server.py"],
      "env": {
        "SNAPCHAT_CLIENT_ID": "your_client_id",
        "SNAPCHAT_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

Restart Claude Desktop. Done.

---

## Available Tools

| Tool | Description |
|---|---|
| `snapchat_get_ad_accounts` | List all ad accounts — **start here** |
| `snapchat_get_campaigns` | All campaigns with budget & status |
| `snapchat_get_ad_squads` | Ad squads with targeting & bid info |
| `snapchat_get_ads` | Individual ads |
| `snapchat_get_performance_stats` | Stats for any campaign / ad squad / ad |
| `snapchat_get_account_report` | Full account-level summary |
| `snapchat_update_status` | Pause or activate any entity |
| `snapchat_update_campaign_budget` | Change daily budget or lifetime cap |
| `snapchat_get_creatives` | List creative assets |

---

## Example Prompts

```
List all my Snapchat ad accounts

Give me a 7-day performance report for account [ID]

Which campaigns have the highest CTR this week?

Pause the Indonesia ad squad — CTR is too low

Update campaign [ID] daily budget to $150

Compare performance across all active ad squads

Rename campaign [ID] to [new name]
```

---

## Budget Values (Micro-Dollars)

Snapchat API uses micro-dollars: `$1 = 1,000,000`

| USD | Micro-dollars |
|-----|--------------|
| $10 | 10,000,000 |
| $50 | 50,000,000 |
| $100 | 100,000,000 |

---

## Antigravity / n8n Integration

See [`AGENT_FLOWS.md`](./AGENT_FLOWS.md) for connecting this MCP to Antigravity agents for automated reporting and optimization workflows.

---


---

## Agency / Multi-Client Setup

Each client gets their own isolated config with their own tokens and org ID.

### Step 1 — Run auth once per client

```bash
python auth_setup.py --client skyline
python auth_setup.py --client fantastic
```

Each run saves to  with org ID locked automatically.

### Step 2 — Add one entry per client in claude_desktop_config.json

```json
{
  mcpServers: {
    snapchat-skyline: {
      command: python3,
      args: [/full/path/to/server.py],
      env: {
        SNAPCHAT_CLIENT_ID: your_app_id,
        SNAPCHAT_CLIENT_SECRET: your_secret,
        SNAPCHAT_CONFIG_FILE: /full/path/to/clients/skyline/config.json
      }
    },
    snapchat-fantastic: {
      command: python3,
      args: [/full/path/to/server.py],
      env: {
        SNAPCHAT_CLIENT_ID: your_app_id,
        SNAPCHAT_CLIENT_SECRET: your_secret,
        SNAPCHAT_CONFIG_FILE: /full/path/to/clients/fantastic/config.json
      }
    }
  }
}
```

> ✅ One OAuth app (your Sigma Digital credentials) works for all clients.
> Each client is fully isolated — wrong org access is blocked at the server level.

### How it works in Claude

You'll see  and  as separate tool sets.
Tell Claude which client to use and it only touches that org's data.

## Troubleshooting

**"CLIENT_ID not set"** → Set env variables before running

**"No tokens found"** → Run `python auth_setup.py`

**"Error 401"** → Token expired, run `python auth_setup.py` again

**"Error 403"** → Check Snapchat Business account has Marketing API access

**Tools not showing in Claude** → Verify path in config and restart Claude Desktop

---

## Built By

[Sigma Digital](https://sigma.digital) — Performance Marketing & AI Automation Agency

---

## License

MIT — free to use, modify, and distribute.