The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the MCP Server Reddit Ads listing page.
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.
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).
If you use Claude Code, let it do the mechanical work. Copy this whole prompt and paste it into Claude Code:
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.
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:
Either way, you still register the Reddit app (step 1 below) and approve the browser login yourself - those cannot be automated.
The full process, for other MCP clients or if you prefer to do it by hand. It takes about five minutes.
http://localhost:8080, and choose a primary contact (a business admin). Save it.Reddit then shows the two values you need in step 2:
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.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.
Run the built-in setup helper:
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:
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).
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:
Claude Code users can register it from the command line instead:
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.
You are connected and read-only. Good first questions:
Most people stay here day to day. When you want to make changes, turn on writes.
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 for exactly what each level unlocks.
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. |
| 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. |
| 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.get_performance_report takes friendly lowercase metric names (impressions, clicks, spend, cpc, conversion_page_visit_clicks, and so on) and validates them locally before the call, suggesting the closest match on a typo.create_ad_group requires a conversion_pixel_id, and create_campaign requires one when campaign budget optimization is on (a Reddit mandate since 2026-07-13). The pixel id is in the Reddit Ads dashboard under Events Manager; in observed data it equals the ad account id.copy_ads duplicates ads into another ad group (Reddit creates a duplicate promoted post per copy) with an option to rewrite utm_campaign and other click-URL query params.allow_comments. To change what an ad says, create a new ad with the new copy, enable it, and pause the old one.The client encodes behaviors verified against the live API. The ones that cause the most confusion:
PATCH, never PUT, and Reddit returns 404 (not 405) for the wrong verb. A verb bug looks exactly like a missing resource. This is the bug that breaks every write in the upstream package./ads/{id}); collections and creates use account-scoped paths (/ad_accounts/{id}/ads). Mixing them returns 404.CONVERSION_SIGN_UP_CLICKS vs CONVERSION_SIGNUP_TOTAL_VALUE). Use the friendly lowercase names; the server validates and maps them.configured_status, not effective_status. The configured value updates immediately; the effective value can lag by minutes.PATCH /posts/{id} permits exactly one field: allow_comments. Headline and body are rejected outright. Changing copy means shipping a new ad (create_ad, born paused) and pausing the old one - which also keeps performance history per message, so it is the right workflow anyway.This software is provided "as is" and "as available", without warranty of any kind, as set out in the LICENSE. It may contain bugs or errors, and any safeguards or controls it provides may fail or behave unexpectedly. Use it at your own risk.
This tool can create, rename, pause, resume, and reconfigure live Reddit advertising entities, and can change budgets, bids, and targeting. These actions can start, increase, or otherwise affect real ad spend. You are solely responsible for:
The author accepts no liability for lost or unintended ad spend, misconfigured or paused campaigns, unintended changes, or any other damages arising from use of this software, including any failure of its safety controls to prevent an action.
This project is an independent, unofficial client. It is not affiliated with, endorsed by, or sponsored by Reddit, Inc.
MIT