mcp-server-reddit-ads is an MCP server for the Reddit Ads API v3, built and validated for its own use by developers who actually run Reddit ads. It provides MCP clients with read and write access to Reddit ad accounts, and restricts operations that may generate spend through tiered safety controls.
Purpose and main capabilities The server provides MCP clients with read access to campaigns, ad groups, ads, and performance reports, while also providing controlled write tools for pausing, creating, modifying budgets and bids, editing targeting, and copying ads between ad groups. The read side exposes 18 tools; the write side is progressively unlocked by tier.
How to use it Prerequisites include: a Reddit ad account with business admin permissions (used to register an app), Node.js 20 or higher, and any MCP client (Claude Code, Claude Desktop, or another). Installation paths fall into three categories: the "paste one prompt" method for Claude Code (recommended, where the client reads the README, runs npx mcp-server-reddit-ads auth, writes .mcp.json, and confirms the server loads); a guided prompt for Claude Desktop (where the client acts as a wizard, and the user runs one command and edits one configuration file themselves); and an advanced manual process for other clients or those who prefer manual operation, taking about five minutes. Key points of the manual process: log in at ads.reddit.com with an account that has business admin permissions; go to Developer Applications in Business settings to create an app, with any name you choose, and the redirect URI must be exactly http://localhost:8080，并选择一位业务管理员作为主要联系人；保存后获取 Client ID (a short string of about 22 characters, often displayed below the app name with no clear label) and Client secret (in a field explicitly labeled secret, which must be copied immediately; if lost, it can be regenerated). Be careful not to use reddit.com/prefs/apps, as that entry point will silently reject new apps under the Responsible Builder Policy. Then run the built-in installation assistant, enter or provide the credentials via REDDIT_CLIENT_ID and REDDIT_CLIENT_SECRET, and the browser will open the Reddit authorization page and at http://localhost:8080 Wait for approval; after approval, credentials can be written directly to disk (existing files will be backed up as <file>.bak and other servers will not be affected), or you can choose to print a pasteable configuration block. If it fails, there are two common causes: port 8080 is already in use, or the redirect URI does not match. After configuration is complete, restart the client, confirm that the server is loaded, and request a list of Reddit ad accounts; you should see the account id (in the form a2_...). If you are managing only one account, you can set REDDIT_ADS_ACCOUNT_ID in the configuration and restart, so that you do not need to specify the account in every request. After connecting, it defaults to read-only, which is suitable for everyday viewing, such as account overview, performance over the last 7 days by campaign, and currently active ad groups.
Write and security tiers A fresh installation cannot pause, create, or edit anything. To allow changes, you need to raise REDDIT_ADS_WRITE_TIER in the configuration and restart. It is recommended to set it to safe first (this tier will not start or increase spending), and only raise it to spend when you truly intend to resume delivery or change budgets, bids, or targeting. Tools above the current tier are not only rejected, but also completely hidden from the client's tool list; even if they are accidentally called, the server will reject them with an error indicating the required tier.
Environment variables and tool details REDDIT_ADS_WRITE_TIER controls the write tier, disables writes by default, and is enabled in two steps. get_campaigns, get_ad_groups, and get_ads support optional status filtering (ACTIVE, PAUSED, ARCHIVED), applied on the client side to configured_status. Tool results are capped at 200,000 characters, and when truncated, a prompt is shown and it is recommended to narrow the query scope. get_performance_report accepts friendly lowercase metric names (such as impressions, clicks, spend, cpc, conversion_page_visit_clicks, etc.) and validates them locally before the call, suggesting the closest match when there is a spelling error. create_ad_group requires conversion_pixel_id, and when campaign budget optimization is enabled, create_campaign also requires this parameter (a Reddit requirement as of 2026-07-13); the pixel id can be found in the Events Manager of the Reddit Ads dashboard found in the observed data, it equals the ad account id. copy_ads can copy an ad to another ad group (each copy makes Reddit create a duplicate promoted post), and optionally rewrite click URL query parameters such as utm_campaign. Ad copy (title, body) cannot be modified through the Reddit API; the only editable post attribute is allow_comments; to change ad content, you need to create a new ad with new copy, enable it, and pause the old ad.
Reddit API notes Updates use PATCH rather than PUT, and Reddit returns 404 instead of 405 for the wrong verb; a wrong verb looks exactly the same as a missing resource, which is a bug in the upstream package that breaks all writes. A single resource is at the bare path (/ads/{id}), while collections and creation use account-scoped paths (/ad_accounts/{id}/ads); mixing them returns 404. All monetary fields are in microcurrency (one millionth of a currency unit); this server converts to dollars when reading and back when writing, so tool inputs and outputs are both in dollars. Report metric names are uppercase enums in requests and lowercase with inconsistent spelling in responses (for example, CONVERSION_SIGN_UP_CLICKS and CONVERSION_SIGNUP_TOTAL_VALUE); using friendly lowercase names is recommended, and the server validates and maps them. After writing, you should trust configured_status rather than effective_status; the former updates immediately, while the latter may lag by several minutes.
Limitations and disclaimer This software is provided "as is" and "as available", without any warranty, may contain errors, and its safety controls may fail or behave abnormally; use at your own risk. This tool can create, rename, pause, resume, and reconfigure real Reddit ad entities, and can change budgets, bids, and targeting; these operations may start, increase, or otherwise affect real ad spend. Users bear the resulting costs, expenses, or financial outcomes themselves, must independently review and verify every change they make, properly safeguard Reddit API credentials, and ensure their use of the Reddit Ads API complies with Reddit's terms. The authors are not liable for lost or accidental ad spend, misconfigured or paused campaigns, unintended changes, or other damages, including cases where its safety controls fail to prevent an operation. This project is an independent unofficial client and has no affiliation, endorsement, or sponsorship relationship with Reddit, Inc.
Use cases Suitable for advertisers and marketers who need to manage Reddit ad accounts in natural language, for daily reading of account overviews and performance reports, as well as operations such as budget, bid, and targeting adjustments and new ad creation under controlled levels. Note that this tool only targets the Reddit Ads API and does not involve other ad platforms, and write capability must be explicitly enabled.
