Reddit Ads MCP server
This is a read-only Reddit Ads MCP server for inspecting ad accounts and their configuration, creative assets, catalogs, and performance reporting.
Health & setup: Read the allowed ad account's business, currency and timezone, plus setup guides, write schemas and reporting catalogs.
Campaign hierarchy: List and read campaigns, ad groups and ads with native configuration and configured/effective status.
Targeting: Read an ad group's actual targeting and discover valid geolocations, languages, interests, devices, carriers and communities.
Reporting: Run native Reddit reports with metrics, up to three breakdowns, explicit UTC dates and cursor pagination.
Audiences & lead forms: Read saved and custom audiences, plus lead form configuration (never lead submissions).
Creative: Browse profile asset libraries, structured posts, upload processing status, post-creation job receipts, and resolved ad creatives/media URLs.
Catalogs: Read product catalogs, products, product sets and catalog imports owned by the ad account's business.
Safety: Every request is scoped to allowlisted ad account IDs; write tools are excluded from this schema and disabled by default.
Provides tools for interacting with the Reddit Ads API (v3), enabling AI agents to read campaigns, ad groups, ads, targeting, audiences and reporting data, and to prepare and confirm write operations on explicitly allowlisted ad accounts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Reddit Ads MCP server show me this week's campaign performance by spend and CTR"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Reddit Ads MCP server
Bring your Reddit Ads accounts into your MCP client.
Read campaigns and reporting, inspect targeting and prepare changes for explicitly allowed ad accounts.
Watch the film · What's new · Install · Tool reference · Try hosted getmcpads

The film shows hosted getmcpads with sample data. Its MCP Apps, from creative galleries and alerts to Google Sheets exports and bulk launches, belong to the hosted product. This repository provides the standalone native API tools.
31 read tools · 22 write tools, disabled by default.
Run locally with your own platform credentials and a client that supports stdio MCP, such as Claude Desktop, Claude Code or Cursor. Your requests go directly to the platform. For managed connections, including supported ChatGPT setups, use the hosted option.
What's new
v1.0.2: Maintainer metadata update · November 8, 2026
List the getmcpads team as maintainer in
package.json, the README andSOURCE_SYNC.md.No change to tools, parameters, descriptions or runtime behaviour.
Earlier releases
Version | Date | Highlights |
1.0.1 | October 26, 2026 | Zod 4 security update |
1.0.0 | October 23, 2026 | First standalone release |
Source synchronization: SOURCE_SYNC.md.
Upgrade notes
Requires Node.js 22.23.4, 24.22.1, 26.12.1 or a newer release of those lines. CI covers Node 22, 24 and 26, and the server prints a warning to stderr on an older runtime. Writes remain optional and require explicit confirmation. Hosted creative integrations and MCP Apps UI are outside this release.
Related MCP server: io.github.seer22/shturman-direct-mcp
Install this release
This is a GitHub source release. npm and MCP Registry versions are published separately. The commands below select this exact version; unpinned npx examples later in this document select the version currently available on npm.
git clone --branch v1.0.2 --depth 1 https://github.com/get-mcp-ads/reddit-ads-mcp-server.git
cd reddit-ads-mcp-server
npm ci
npm run buildConfigure your MCP client to run node with the absolute path to dist/cli.js and the platform credentials documented below. Once the package is on npm, the same server runs with npx -y @getmcpads/reddit-ads-mcp-server. A Claude Desktop entry looks like this:
{
"mcpServers": {
"reddit-ads": {
"command": "npx",
"args": ["-y", "@getmcpads/reddit-ads-mcp-server"],
"env": {
"REDDIT_ADS_REFRESH_TOKEN": "your-refresh-token",
"REDDIT_ADS_CLIENT_ID": "your-app-client-id",
"REDDIT_ADS_CLIENT_SECRET": "your-app-secret",
"REDDIT_ADS_ACCOUNT_IDS": "a2_abc123"
}
}
}
}Managed connection. Use Reddit Ads with hosted getmcpads. Connect your account, select the data your assistant may access and use the hosted MCP connection. See the site for current features and plans.
Configuration
Provide these environment variables through the client's secret configuration:
Variable | Purpose |
| OAuth access token with |
| Permanent refresh token. With the two variables below, the server renews access tokens in memory. |
| Client ID of your Reddit app, needed with the refresh token. |
| Secret of your Reddit app, needed with the refresh token. |
| Required comma-separated ad account IDs, such as |
| Defaults to |
| Optional. Reddit asks clients to identify themselves, for example |
Register a developer application and request Ads API access as described in Reddit's Ads API documentation. Then run Reddit's OAuth authorization code flow with the scopes adsread, plus adsedit only if you plan to enable writes, and duration=permanent to receive a refresh token.
Reddit access tokens expire after about an hour. Give the refresh token and the app credentials for daily use; an access token alone works until it expires.
This package accepts tokens. It does not run an OAuth browser flow and never writes a renewed token to disk. Reddit ad account IDs start with a2_; the business ID is a different value.
npm run doctor reports which variables are set, without printing any value, and whether your Node.js release carries the October 2026 security fixes. Run reddit_health_check as the first call: it reads the account, its business, currency and timezone.
Safety and coverage
Writes preview by default. Review the exact account, target and payload before repeating the call with confirm: true.
Campaigns, ad groups and ads are created paused. Activation can spend advertising budget, and previews that set configured_status to ACTIVE say so with activationMaySpend.
Do not retry a write automatically when its result is uncertain. Read the account and reconcile it first. The server retries only after an HTTP 401, once, when it renewed the token, because Reddit rejected that request before acting on it.
The account allowlist applies before every request. Each entity read is checked against the ad account, directly or through its profile, business or catalog. Before a confirmed write, the campaigns, ad groups, posts, audiences, pixels, product sets, profiles and assets it references are checked the same way.
Write payloads are validated against Reddit's schemas pinned on 2026-09-11. Billing fields and computed statuses are refused. Passing local validation is not provider acceptance.
Budgets, bids and SPEND are microcurrency: one millionth of the account currency. Other reporting fields keep their native units. Pagination cursors are Reddit's own page tokens.
Requests go only to ads-api.reddit.com and, for token renewal, www.reddit.com. No request follows a redirect. Each one has a timeout and a response size limit. Credentials are redacted from every result and error.
Media URLs that Reddit returns are passed on as data. This server never downloads them.
Some Reddit capabilities are intentionally not exposed:
Customer-list member uploads and conversion event injection.
Lead submissions and any other download of personal records. Lead forms are readable as configuration only.
Product feeds, billing and funding instruments.
Destructive deletes. Status updates accept
PAUSEDandACTIVEonly, and saved audiences cannot be set toDELETED.Onsite lead-form creation, which Reddit ended on September 21, 2026.
This server exposes a reviewed subset of the Reddit Ads API. It does not automatically expose new upstream endpoints. Hosted creative galleries, alerts, exports and MCP Apps UI are excluded.
Use tools/list or server-card.json for exact schemas, reddit_get_write_schema for the pinned write schemas and Reddit's API reference for provider details.
Hosted option
getmcpads for Reddit Ads manages the hosted connection and account selection. Hosted and source releases can differ. Contact: hello@getmcpads.com.
Development
npm run typecheck
npm run lint
npm run build
npm test
npm run catalogAll tests run offline with synthetic responses. No live account is changed.
Tools
Every tool is listed below. See server-card.json for complete parameter and output schemas.
Tool | Purpose |
| Coverage, prerequisites, units, renaming and known limits of this server |
| Pinned native schema for one write operation, including targeting and formats |
| Every reporting metric and breakdown name Reddit accepts |
| Read the allowed ad account, its business, currency and timezone |
| List campaigns with native configuration and status |
| Read one campaign after checking its account |
| List ad groups with native configuration and status |
| Read one ad group after checking its account |
| List ads with native configuration and status |
| Read one ad after checking its account |
| List saved audiences |
| Read one saved audience after checking its account |
| List custom audiences |
| Read one custom audience after checking its account |
| List lead form configurations, never lead submissions |
| Read one lead form configuration after checking its account |
| Read the configured targeting of an ad group |
| Discover valid geolocations, languages, interests, devices, carriers and communities |
| List profiles attached to the ad account |
| List pixels available to the ad account |
| Run a native report with metrics, up to three breakdowns, UTC dates and pagination |
| List the asset library of an attached profile |
| List structured posts of an attached profile |
| Read one structured post after checking its profile |
| Poll the processing of creative asset imports |
| Poll a structured post creation job with its signed receipt |
| Resolve the images and videos behind ads, with explicit coverage |
| List product catalogs of the business that owns the ad account |
| List products of an owned catalog |
| List product sets of an owned catalog |
| List catalog imports of an owned catalog |
Disabled by default. Calls preview unless explicitly confirmed. Check the configuration and exact schema before use.
Tool | Purpose |
| Create a campaign, always paused |
| Update campaign fields, including pause or reactivation |
| Create an ad group, always paused |
| Update ad group fields, including targeting, bids and status |
| Create an ad, always paused |
| Update ad fields, including pause or reactivation |
| Create a saved audience |
| Update a saved audience, without deletion |
| Create a pixel, engagement or empty customer-list audience |
| Import images, videos or headlines into a profile's asset library |
| Start a structured post creation job and return its receipt |
| Create a product catalog for the owning business |
| Create a product set in an owned catalog |
| Create or update products in an owned catalog |
| Rename a campaign, nothing else |
| Rename an ad group, nothing else |
| Rename an ad, nothing else |
| Rename the ad account, nothing else |
| Change whether comments are allowed on a structured post |
| Rename a creative asset |
| Update a catalog's name or event sources |
| Update a product set's name or filter |
Resources
Resource | Content |
| The setup guide, also returned by |
| Every metric with its category and unit note, and every dimension with whether it is a breakdown |
License
Apache License 2.0. See NOTICE.
More from getmcpads
Meta Ads · Google Ads · Google Analytics 4 · Google Search Console · TikTok Ads · Pinterest Ads · X Ads
Maintained by the getmcpads team at getmcpads. Questions: hello@getmcpads.com.
Available Tools
31 toolsreddit_get_adreddit get adARead-onlyIdempotent
Read one Reddit ad and verify that it belongs to the ad account.
Inputs: id (required), adAccountId (required). Returns: result
reddit_get_ad_groupreddit get ad groupARead-onlyIdempotent
Read one Reddit ad group and verify that it belongs to the ad account.
Inputs: id (required), adAccountId (required). Returns: result
reddit_get_ad_groupsreddit get ad groupsARead-onlyIdempotent
Read Reddit ad groups, including native configuration and configured/effective status. Pagination returns an opaque cursor; every further page needs an explicit call.
Inputs: adAccountId (required), limit, cursor. Returns: result
reddit_get_adsreddit get adsARead-onlyIdempotent
Read Reddit ads, including native configuration and configured/effective status. Pagination returns an opaque cursor; every further page needs an explicit call.
Inputs: adAccountId (required), limit, cursor. Returns: result
reddit_get_asset_uploadsreddit get asset uploadsBRead-onlyIdempotent
Poll processing of creative imports through the profile; ACTIVE is media-ready, not advertising delivery.
Inputs: profileId (required), uploadIds (required), adAccountId (required). Returns: result
reddit_get_campaignreddit get campaignARead-onlyIdempotent
Read one Reddit campaign and verify that it belongs to the ad account.
Inputs: id (required), adAccountId (required). Returns: result
reddit_get_campaignsreddit get campaignsARead-onlyIdempotent
Read Reddit campaigns, including native configuration and configured/effective status. Pagination returns an opaque cursor; every further page needs an explicit call.
Inputs: adAccountId (required), limit, cursor. Returns: result
reddit_get_catalog_importsreddit get catalog importsBRead-onlyIdempotent
Read catalog imports from a catalog owned by the ad account's business.
Inputs: catalogId (required), adAccountId (required), limit, cursor. Returns: result
reddit_get_catalogsreddit get catalogsBRead-onlyIdempotent
Read product catalogs of the business owning the ad account.
Inputs: adAccountId (required), limit, cursor. Returns: result
reddit_get_creative_assetsreddit get creative assetsARead-onlyIdempotent
List the asset library of a profile attached to the ad account; unused files are not necessarily ads.
Inputs: profileId (required), adAccountId (required), limit, cursor. Returns: result
reddit_get_custom_audiencereddit get custom audienceARead-onlyIdempotent
Read one Reddit custom audience and verify that it belongs to the ad account.
Inputs: id (required), adAccountId (required). Returns: result
reddit_get_custom_audiencesreddit get custom audiencesARead-onlyIdempotent
Read Reddit custom audiences, including native configuration and configured/effective status. Pagination returns an opaque cursor; every further page needs an explicit call.
Inputs: adAccountId (required), limit, cursor. Returns: result
reddit_get_insightsreddit get insightsARead-onlyIdempotent
Native Reddit reporting with metrics and entity/audience breakdowns, explicit UTC dates and pagination. Empty results validate transport only. Reported audience demographics differ from configured targeting.
Inputs: endsAt (required), fields (required), startsAt (required), adAccountId (required), +4 more. Returns: result
reddit_get_lead_formreddit get lead formARead-onlyIdempotent
Read one Reddit lead form and verify that it belongs to the ad account. Form configuration only; lead submissions are never returned.
Inputs: id (required), adAccountId (required). Returns: result
reddit_get_lead_gen_formsreddit get lead gen formsARead-onlyIdempotent
Read Reddit lead gen forms, including native configuration and configured/effective status. Form configuration only; lead submissions are never returned. Pagination returns an opaque cursor; every further page needs an explicit call.
Inputs: adAccountId (required), limit, cursor. Returns: result
reddit_get_pixelsreddit get pixelsARead-onlyIdempotent
List pixels accessible to the allowed Reddit ad account.
Inputs: adAccountId (required), limit, cursor. Returns: result
reddit_get_postreddit get postARead-onlyIdempotent
Read an ad structured post after profile ownership verification.
Inputs: id (required), adAccountId (required). Returns: result
reddit_get_post_jobreddit get post jobARead-onlyIdempotent
Poll a previously created structured post using its signed job receipt. Does not accept arbitrary job IDs from another account.
Inputs: receipt (required), adAccountId (required). Returns: result
reddit_get_postsreddit get postsBRead-onlyIdempotent
List advertising structured posts for a profile attached to this account. Returns native image/video/carousel/text configuration.
Inputs: profileId (required), adAccountId (required), limit, cursor. Returns: result
reddit_get_productsreddit get productsBRead-onlyIdempotent
Read products from a catalog owned by the ad account's business.
Inputs: catalogId (required), adAccountId (required), limit, cursor. Returns: result
reddit_get_product_setsreddit get product setsBRead-onlyIdempotent
Read product sets from a catalog owned by the ad account's business.
Inputs: catalogId (required), adAccountId (required), limit, cursor. Returns: result
reddit_get_profilesreddit get profilesARead-onlyIdempotent
List profiles accessible to the allowed Reddit ad account.
Inputs: adAccountId (required), limit, cursor. Returns: result
reddit_get_reporting_schemareddit get reporting schemaARead-onlyIdempotent
Reddit metric and dimension inventory; configured targeting is read with reddit_get_targeting, not inferred from reporting.
Inputs: no named parameters. Returns: result
reddit_get_saved_audiencereddit get saved audienceARead-onlyIdempotent
Read one Reddit saved audience and verify that it belongs to the ad account.
Inputs: id (required), adAccountId (required). Returns: result
reddit_get_saved_audiencesreddit get saved audiencesARead-onlyIdempotent
Read Reddit saved audiences, including native configuration and configured/effective status. Pagination returns an opaque cursor; every further page needs an explicit call.
Inputs: adAccountId (required), limit, cursor. Returns: result
reddit_get_setup_guidereddit get setup guideARead-onlyIdempotent
Reddit connector coverage, prerequisites, units, renaming and known limits. Read it before planning writes or answering what this server cannot do.
Inputs: no named parameters. Returns: result
reddit_get_targetingreddit get targetingARead-onlyIdempotent
Read actual ad-group targeting: inclusions, exclusions, geo, age/gender, languages, interests, communities, keywords, devices and audience IDs. This is configuration, not delivery demographics.
Inputs: adGroupId (required), adAccountId (required). Returns: result
reddit_get_targeting_optionsreddit get targeting optionsBRead-onlyIdempotent
Discover valid native targeting values. Communities can be searched; large lists are paginated or explicitly marked partial.
Inputs: kind (required), adAccountId (required), limit, query, +2 more. Returns: result
reddit_get_write_schemareddit get write schemaARead-onlyIdempotent
Exact pinned native schemas for Reddit creation and edits, including targeting and all implemented campaign/ad formats. Provider acceptance is separate from local schema validation.
Inputs: operation (required). Returns: result
reddit_health_checkreddit health checkARead-onlyIdempotent
Read the allowed Reddit ad account, its business, currency and timezone. API access is not proof of delivery or full objective eligibility.
Inputs: adAccountId (required). Returns: result
reddit_list_ad_creativesreddit list ad creativesARead-onlyIdempotent
Resolve ad-linked image/video/carousel assets with explicit coverage. A video cover does not establish its motion/audio; use full media when available. Media URLs are returned, never downloaded.
Inputs: adAccountId (required), adIds, limit, cursor. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 31 tools
The dominant list-vs-single pattern (reddit_get_campaigns / reddit_get_campaign, ads/ad, audiences, lead forms) is clearly conventional and easy to route between. The only genuinely soft boundaries are in the creative cluster (reddit_get_creative_assets vs reddit_list_ad_creatives vs reddit_get_asset_uploads vs reddit_get_posts/reddit_get_post) and targeting vs targeting_options, but the descriptions draw explicit distinctions there.
Nearly every tool follows reddit_<verb>_<noun> with 'get' as the verb, which makes the surface predictable. Minor deviations exist: reddit_health_check has no verb_noun form, reddit_list_ad_creatives uses 'list' where every comparable tool uses 'get', and the lead-form pair is inconsistently named (reddit_get_lead_form vs reddit_get_lead_gen_forms).
31 tools is well past the heavy threshold, and much of the volume comes from mechanical list/get duplication across ten entity types rather than distinct capabilities. The domain is genuinely broad, but a read-only surface this size would be better served by fewer, parameterized read tools plus the write operations that are conspicuously absent.
The surface is entirely read-only: despite exposing reddit_get_write_schema for 'creation and edits', there is no tool to create, update, pause, or delete a campaign, ad group, ad, audience, or budget. Read coverage is deep (entities, targeting, reporting, catalogs, creative), but an agent asked to actually run Reddit ads hits a dead end at the first write.
Maintenance
Related MCP Connectors
Google Ads MCP server: 17 tools for reporting, campaigns, keywords, assets. Writes preview first.
Read and manage Meta Ads campaigns, ad sets, ads, audiences, pages and Business Manager. You provide
Push, email, SMS, in-app and journeys. 231 tools: reads, drafts, app setup; only test sends.
Query marketing data across 20+ ad platforms; with write access, create, schedule and share reports.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides read-only access to Meta Ads API, enabling campaign management, creative analysis, targeting research, and performance analytics via 39 tools.-
- AlicenseAqualityBmaintenanceEnables safe, informed management of Yandex.Direct accounts through 11 MCP tools, covering reads, planned two-phase writes, reports, media attachment, Wordstat, Metrika, and Audience operations, while exposing platform knowledge as resources such as limits, traps, and the red line of deliberately absent destructive actions.11MIT
- AlicenseNot gradedqualityDmaintenanceEnables reading and managing Meta Ads campaigns, ad sets, ads, audiences, pages, and Business Manager using a long-lived access token and Facebook App ID. It provides 38 read/write tools and works with any MCP client over HTTP.MIT
- AlicenseBqualityBmaintenanceEnables MCP clients to read Snapchat Ads campaigns and performance and to prepare preview-first changes for selected ad accounts, with opt-in write tools and explicit confirmation before applying updates.21131 npmApache 2.0