reddit-ads-mcp

A small, self-hosted MCP server for the Reddit Ads API v3, in Python.

• Read accounts, campaigns, ad groups, ads, and performance reports.
• Write (opt-in) — pause/activate, set budgets, patch fields, create entities.
• No third party. Auth is a direct OAuth2 refresh-token exchange with reddit.com using your app credentials. Nothing is proxied anywhere.
• Safe by default. Mutations are refused unless REDDIT_ADS_WRITE_ENABLED=true.

Inspired by the read-only C# RedditAdsMcp; rewritten in Python with opt-in write support and a self-hosted token helper.

Status: reads + the core small-writes (status / budget / field patch) are verified against the live Reddit Ads API v3 (2026-06-30). create_* are wired but not yet validated end-to-end — marked experimental below.

Tools

Tool	Access	Description
list_accounts	read ✓	All ad accounts reachable with your credentials
list_campaigns	read ✓	Campaigns for an account
list_ad_groups	read ✓	Ad groups, optionally by campaign_id
list_ads	read ✓	Ads, optionally by ad_group_id
get_performance_report	read ✓	Custom date range / fields / breakdowns
get_daily_performance	read ✓	Last N days by DATE + CAMPAIGN_ID
set_campaign_status / set_ad_group_status	write ✓	Pause / activate / archive
set_campaign_budget / set_ad_group_budget	write ✓	Daily budget in dollars (auto micro-conversion)
update_campaign / update_ad_group	write ✓	Patch arbitrary fields
create_campaign / create_ad_group	write ⚠️	Create entities (experimental — unvalidated)

Write tools are only registered when REDDIT_ADS_WRITE_ENABLED=true.

API notes (learned from the live v3 API)

• Collections are nested, single entities are top-level: list/create use ad_accounts/{id}/campaigns, but get/update use campaigns/{id} (no account prefix).
• Budgets are micro-currency: goal_value: 6000000 = $6.00, goal_type: "DAILY_SPEND". The set_*_budget tools take plain dollars and convert for you.
• Reports are a read-only POST to ad_accounts/{id}/reports with a {data:{…}} body.
• Write OAuth scope is adsedit (not adswrite).

Setup

1. Create a Reddit Ads API app

ads.reddit.com → Developer Applications → Create a new app. Set the redirect URI to any HTTPS URL you control — it only needs to show the code query param Reddit appends after you click Allow. Copy the App ID and Secret.

2. Get a refresh token (one-time)

Open this URL (URL-encode your redirect; drop %20adsedit for read-only):

https://www.reddit.com/api/v1/authorize?client_id=YOUR_APP_ID&response_type=code&state=mcp&redirect_uri=YOUR_REDIRECT&duration=permanent&scope=adsread%20adsedit

Click Allow, copy the code from the redirected URL, then:

python scripts/get_refresh_token.py \
  --client-id YOUR_APP_ID --client-secret YOUR_SECRET \
  --code THE_CODE --redirect-uri YOUR_REDIRECT

It prints your permanent REDDIT_ADS_REFRESH_TOKEN.

3. Find your account ID

ads.reddit.com → account dropdown — it looks like a2_xxxxxxxx.

4. Configure your MCP client

With uv (no global install needed):

{
  "mcpServers": {
    "reddit-ads": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/reddit-ads-mcp", "python", "-m", "reddit_ads_mcp"],
      "env": {
        "REDDIT_ADS_CLIENT_ID": "your_app_id",
        "REDDIT_ADS_CLIENT_SECRET": "your_secret",
        "REDDIT_ADS_REFRESH_TOKEN": "your_refresh_token",
        "REDDIT_ADS_ACCOUNT_ID": "a2_xxxxxxxx",
        "REDDIT_ADS_WRITE_ENABLED": "false"
      }
    }
  }
}

Flip REDDIT_ADS_WRITE_ENABLED to "true" only when you want mutations (and only if the refresh token was granted the adsedit scope).

Development

uv sync
uv run python -m reddit_ads_mcp   # starts the stdio server (needs env vars)

License

MIT © Sorin Mihailescu