mcp-server-reddit-ads

# MCP Server for Reddit Ads (mcp-server-reddit-ads)

A Reddit Ads API v3 MCP server with working write operations and tiered safety controls, built and dogfooded by an actual Reddit advertiser. It gives an MCP client read access to campaigns, ad groups, ads, and performance reports, plus gated write tools for pausing, creating, budget and bid changes, targeting edits, and copying ads between ad groups.

## Requirements

- A Reddit Ads account, with business-admin access so you can register an app.
- Node.js 20 or newer.
- An MCP client (Claude Code, Claude Desktop, or any other).

## Getting started

Pick the path that matches your setup: a paste-one-prompt route for Claude Code or Claude Desktop, or the manual steps for any other client. Every path installs read-only and cannot change anything in your account until you deliberately turn on writes (the last step).

### Simple setup with Claude Code (recommended)

If you use Claude Code, let it do the mechanical work. Copy this whole prompt and paste it into Claude Code:

```text
Set up the mcp-server-reddit-ads MCP server for me so I can manage my Reddit Ads
account from here. Install it read-only for now - no write access. Please:

1. Read the setup instructions at https://github.com/camlowe/mcp-server-reddit-ads
2. Check I'm on Node.js 20 or newer.
3. Walk me through registering a Reddit app, since only I can do that part. Tell me
   exactly where to click and which two values (client ID and client secret) to copy.
4. Run `npx mcp-server-reddit-ads auth` and guide me through the browser login.
5. Add the server to my .mcp.json using the credentials from the auth step, with the
   write tier set to read-only.
6. Confirm the server loads and list my Reddit ad accounts to prove it works.

Do not enable any write access yet. I'll ask for that later when I'm ready.
```

Claude reads this README, tells you exactly what to do for the parts only you can do, runs `npx mcp-server-reddit-ads auth`, writes your `.mcp.json`, and confirms the server loads. Later, when you want to make changes, just ask it to raise the write tier.

### Simple setup with Claude Desktop

Claude Desktop can't run terminal commands for you, so this prompt has it act as a patient guide while you run one command and edit one config file. Paste it into a new Claude Desktop chat:

```text
I want to set up the mcp-server-reddit-ads MCP server so I can manage my Reddit Ads
account with you. I'm not a developer, so please guide me one step at a time with
simple, copy-pasteable instructions, and wait for me to confirm each step before
moving to the next.

Look up the setup details at https://github.com/camlowe/mcp-server-reddit-ads. The
main steps are: register a Reddit app to get a client ID and secret, run a one-time
`npx mcp-server-reddit-ads auth` command in my terminal to log in, and add the server
to my Claude Desktop config file. Set it up read-only so nothing in my account can
change until I decide to turn writes on.
```

Either way, you still register the Reddit app (step 1 below) and approve the browser login yourself - those cannot be automated.

### Advanced setup (manual)

The full process, for other MCP clients or if you prefer to do it by hand. It takes about five minutes.

#### 1. Register a Reddit app

1. Open the Reddit Ads dashboard at [ads.reddit.com](https://ads.reddit.com) and sign in with an account that has business-admin access.
2. Open **Business settings** (the gear / settings menu, top right), then **Developer Applications**, then **Create App**.
3. Give the app a name, set the **redirect URI** to exactly `http://localhost:8080`, and choose a primary contact (a business admin). Save it.

Reddit then shows the two values you need in step 2:

- **Client ID** - the short string (roughly 22 characters, for example `Ab3xK9zQ1rStUvWxYzAbCd`) displayed directly under the app's name. Reddit often shows it without a "client ID" label, so it is easy to miss; it is the code beneath the app title, not the app name itself.
- **Client secret** - the longer value shown in the field explicitly labeled **secret**. Copy it right away; if you lose it you can regenerate a new secret from the same page.

Do not use reddit.com/prefs/apps: it silently rejects new apps under the Responsible Builder Policy, so the Ads developer portal is the only working path for advertisers.

#### 2. Mint a refresh token

Run the built-in setup helper:

```bash
npx mcp-server-reddit-ads auth
```

It asks for the client ID and secret from step 1 (or reads them from `REDDIT_CLIENT_ID` and `REDDIT_CLIENT_SECRET` if you have set them), opens the Reddit authorization page in your browser, and waits on `http://localhost:8080` for you to approve.

Once you approve, it offers to save the configuration for you:

```
Where should I save this? (I'll patch the file, keeping anything already there.)
  [1] Claude Code    ./.mcp.json
  [2] Claude Desktop <your platform's claude_desktop_config.json>
  [3] Just print it  (don't write any file)
```

Pick [1] or [2] and it writes the credentials straight to disk (backing up any existing file to `<file>.bak` and leaving other servers untouched), so nothing sensitive has to pass through your MCP client. If you prefer to place it yourself, pick [3] and it prints a ready-to-paste block instead. When it can't detect a TTY (for example, piped output), it skips the menu and prints the block.

If it fails, it tells you how to fix the two common causes: port 8080 already in use, and a redirect-URI mismatch (the app's redirect URI must be exactly `http://localhost:8080`).

#### 3. Add the server to your MCP client

If you picked [1] or [2] in step 2, this is already done - skip to step 4. Otherwise, paste the printed block into your client's config. It has this shape, with the three credential values already populated by the `auth` command:

```json
{
  "mcpServers": {
    "reddit-ads": {
      "command": "npx",
      "args": ["-y", "mcp-server-reddit-ads"],
      "env": {
        "REDDIT_CLIENT_ID": "your-client-id",
        "REDDIT_CLIENT_SECRET": "your-client-secret",
        "REDDIT_REFRESH_TOKEN": "your-refresh-token",
        "REDDIT_ADS_WRITE_TIER": "read"
      }
    }
  }
}
```

Claude Code users can register it from the command line instead:

```bash
claude mcp add reddit-ads \
  -e REDDIT_CLIENT_ID=your-client-id \
  -e REDDIT_CLIENT_SECRET=your-client-secret \
  -e REDDIT_REFRESH_TOKEN=your-refresh-token \
  -e REDDIT_ADS_WRITE_TIER=read \
  -- npx -y mcp-server-reddit-ads
```

#### 4. Restart and verify

Restart your client so it picks up the server (in Claude Code, approve the server when prompted, and confirm it loaded with `/mcp`). Then ask it to **list your Reddit ad accounts**. You should see your account id (`a2_...`). If you manage a single account, set `REDDIT_ADS_ACCOUNT_ID` to that id in the config and restart, so you never have to name the account in a request again.

#### 5. Try some read-only queries

You are connected and read-only. Good first questions:

- "Give me an overview of my Reddit ad account."
- "Show the last 7 days of performance by campaign."
- "Which of my ad groups are currently active?"

Most people stay here day to day. When you want to make changes, turn on writes.

#### 6. Turn on writes when you need them

A fresh install cannot pause, create, or edit anything. To allow changes, raise `REDDIT_ADS_WRITE_TIER` in your config and restart. Start with `safe` (nothing at that level can start or grow spend) and move to `spend` only when you intend to resume delivery or change budgets, bids, or targeting. See [Write tiers](#write-tiers) for exactly what each level unlocks.

## Write tiers

Writes are off by default. `REDDIT_ADS_WRITE_TIER` opens them in two steps, so an accident at the read or safe tier cannot start spending money.

Tools above the configured tier are not just refused - they are hidden from the client's tool list entirely. A read-only session exposes 18 tools; the model cannot even attempt `update_budget` because it does not know the tool exists. If a hidden tool is somehow called anyway, the server refuses it with an error naming the tier that would unlock it.

| Tier | What it allows | Rule |
|---|---|---|
| `read` (default) | No writes. | Reads only. |
| `safe` | Pause, create (born paused), rename, copy ads. | Cannot start or expand delivery. |
| `spend` | Everything in `safe`, plus enable, budget, bid, and targeting changes. | Can start, resume, or reshape delivery. |

### Environment variables

| Variable | Meaning |
|---|---|
| `REDDIT_CLIENT_ID`, `REDDIT_CLIENT_SECRET`, `REDDIT_REFRESH_TOKEN` | Required. Startup fails with a pointer to the `auth` command if any is missing. |
| `REDDIT_ADS_WRITE_TIER` | `read` (default), `safe`, or `spend`. |
| `REDDIT_ADS_ACCOUNT_ID` | Optional default account (`a2_...`) so single-account users never pass `account_id`. |

## Tools

| Group | Tools | Tier |
|---|---|---|
| Diagnostics | `get_server_status` | read |
| Accounts | `get_accounts`, `get_account_overview` | read |
| Entities | `get_campaigns`, `get_campaign`, `get_ad_groups`, `get_ad_group`, `get_ads`, `get_ad` | read |
| Creative | `get_ad_creative` | read |
| Search | `find_entity` | read |
| Reporting | `get_performance_report`, `get_daily_performance`, `compare_periods`, `compare_ads` | read |
| Targeting data | `search_subreddits`, `get_interest_categories`, `search_geo_targets` | read |
| Create | `create_campaign`, `create_ad_group`, `create_ad` | safe |
| Pause / rename | `pause_items`, `update_name` | safe |
| Comments | `update_ad_comments` | safe |
| Workflows | `copy_ads` | safe |
| Resume | `enable_items` | spend |
| Money | `update_budget`, `update_bid` | spend |
| Delivery shape | `update_targeting` | spend |
| Ad URL | `update_ad_url` | spend |

Notes:

- `get_campaigns`, `get_ad_groups`, and `get_ads` take an optional `status` filter (`ACTIVE`, `PAUSED`, or `ARCHIVED`), applied client-side on `configured_status`.
- Too