Which integrations are available for this server?

Provides tools for managing Reddit Ads accounts, campaigns, ad groups, and ads via the Reddit Ads API v3, including reading performance reports, pausing/activating entities, setting budgets, and patching fields.

How do I use reddit-ads-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@reddit-ads-mcp list my accounts" 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

by FarahTrip

Overview Schema Source Related Servers Discussions Admin

Python

Remote

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).

Related MCP server: mcp-reddit-ads

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

Available Tools

6 tools

get_daily_performanceB

Last N days (default 7) of impressions/clicks/spend/CTR/CPC/eCPM, by DATE + CAMPAIGN_ID.

ParametersJSON Schema

Name	Required	Description	Default
`days`	No
`account_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits. It mentions the default window (7 days) and lists returned metrics, but does not state whether the tool is read-only, requires authentication, or has rate limits. The lack of transparency about side effects or data freshness is a gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that packs essential information: timeframe, metrics, and grouping dimensions. No superfluous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has few parameters and an output schema, so the description could suffice. However, it does not address edge cases (e.g., empty data) or provide context on how metrics are calculated. The output schema likely documents return values, but the description could still be more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description covers the 'days' parameter by indicating it sets the 'last N days' window with a default of 7. However, the 'account_id' parameter is not explained at all; the description does not clarify its role or optionality. Given 0% schema coverage, the description partially compensates but remains incomplete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns daily performance metrics (impressions, clicks, spend, etc.) grouped by date and campaign ID, with a configurable lookback window. However, it does not explicitly differentiate from sibling tool 'get_performance_report', which might serve a similar purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool over alternatives, nor does it mention scenarios where it should not be used. For example, it does not explain how it differs from 'get_performance_report' or when to use 'list_campaigns' instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_performance_reportB

Performance report for a date range (YYYY-MM-DD).

fields default to IMPRESSIONS, CLICKS, SPEND, CTR, CPC, ECPM. breakdowns default to [DATE]; common values: DATE, CAMPAIGN_ID, AD_GROUP_ID, AD_ID.

ParametersJSON Schema

Name	Required	Description	Default
`fields`	No
`end_date`	Yes
`account_id`	No
`breakdowns`	No
`start_date`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden for behavioral disclosure. It does not mention read-only nature, required permissions, error handling, or response format. Only defaults are described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise, with two sentences covering purpose, date format, and defaults. No unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and there are 5 parameters, the description covers defaults but omits explanation for optional parameter 'account_id' and does not differentiate from sibling tools. It is partially complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning by listing default values for 'fields' and 'breakdowns', and common breakdown values. However, it does not describe other parameters like 'account_id' or the expected format for custom field/breakdown arrays.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves a performance report for a date range, specifying the date format. However, it does not differentiate from the sibling tool 'get_daily_performance', which likely has a similar purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like 'get_daily_performance'. Context about when to choose this tool is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_accountsA

List every Reddit ad account reachable with the current credentials (walks /me/businesses → businesses/{id}/ad_accounts).

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description discloses the internal walking mechanism ('walks /me/businesses → businesses/{id}/ad_accounts'), providing good insight into the tool's behavior. However, it lacks details on rate limits or authorization nuances.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with a helpful parenthetical, front-loading the core action and resource without unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the underlying API calls and the scope of results. Though an output schema exists, the description provides sufficient context for a list tool; however, details about potential pagination or limits are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters and 100% schema coverage, the description adds context about the scope of results ('every account reachable'), meeting the baseline expectation for parameterless tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List') and the resource ('every Reddit ad account reachable with the current credentials'), differentiating it from sibling tools focused on performance, ad groups, ads, and campaigns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for discovering accounts accessible to the current credentials but does not explicitly state when to use this tool versus alternatives or provide any exclusion conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_ad_groupsC

List ad groups for an ad account, optionally filtered by campaign_id.

ParametersJSON Schema

Name	Required	Description	Default
`account_id`	No
`campaign_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Lacks disclosure of auth needs, rate limits, data freshness, pagination, ordering, or other behavioral traits. Very minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence of 14 words, no fluff. Could be slightly more informative without losing conciseness, but current length is acceptable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description omits key context like required parameters (both optional?), behavior when filters absent, and return value summary. Incomplete for a simple list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage; parameter titles repeat names. Description adds only that campaign_id is optional, but does not explain semantics, types, or constraints. Minimal value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb (List), resource (ad groups), and scope (for an ad account, optional filter by campaign_id). Distinguishes from sibling tools list_ads, list_campaigns, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. Does not mention prerequisites, scenarios, or when to avoid. Only implies usage by stating the basic function.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_adsA

List ads for an ad account, optionally filtered by ad_group_id.

ParametersJSON Schema

Name	Required	Description	Default
`account_id`	No
`ad_group_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, yet the description only states the basic action without disclosing behavioral traits such as read-only nature, authentication needs, or pagination. For a list operation, minimal context is provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no unnecessary words. Every word contributes to defining the tool's action and optional filter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with 2 optional parameters and an output schema, the description is adequate but lacks mention of required context (e.g., account_id effectively needed) or integration with sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description maps account_id to 'for an ad account' and ad_group_id to filtering, adding meaning beyond the schema (which lacks descriptions). However, with 0% schema description coverage, it only provides basic mapping without details on format or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and resource 'ads' in the context of an ad account, with an optional filter by ad_group_id. It effectively distinguishes from sibling tools like list_accounts, list_ad_groups, and list_campaigns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing ads, optionally filtered by ad_group_id, but lacks explicit guidance on when to use this instead of alternatives or prerequisites like requiring an account_id.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_campaignsA

List campaigns for an ad account (defaults to REDDIT_ADS_ACCOUNT_ID).

ParametersJSON Schema

Name	Required	Description	Default
`account_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description must convey behavioral traits. It only mentions the default account ID, omitting details like read-only nature, pagination, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single, front-loaded sentence with no unnecessary words. Every part contributes to understanding the tool's core function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a simple list tool given the output schema exists, but lacks information on pagination, error handling, or filtering capabilities.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description adds meaningful context by explaining the default behavior of account_id, beyond the schema's bare type and default null.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists campaigns for an ad account, with a specific verb and resource. It differentiates from sibling tools like list_ad_groups and list_ads.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives like list_accounts or list_ad_groups. The default account ID is noted but context for selection is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv0.1.0Jul 7, 2026
- First observedget_daily_performance
- First observedget_performance_report
- First observedlist_accounts
- First observedlist_ad_groups
- First observedlist_ads
- First observedlist_campaigns

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored 2026-07-07 09:50 across 6 tools

Disambiguation4/5

The list tools are clearly distinct by entity, but the two performance tools (get_daily_performance vs get_performance_report) overlap in purpose. Although one is for recent days and the other for custom date ranges, an agent might misselect them without careful description reading.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case (get_*, list_*). The naming is predictable and clear.

Tool Count5/5

With 6 tools, the set is well-scoped for an ad management server. It covers essential entities (accounts, campaigns, ad groups, ads) and reporting, without unnecessary redundancy.

Completeness2/5

The tool surface is read-only: only listing and reporting. Missing write operations (create, update, delete) for campaigns, ads, etc., which are critical for actual ad management. Agents cannot perform any operational tasks.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

reddit-scraperOAuth
io.github.fashionmascherine-svg
Reddit MCP server: search posts, subreddit feeds, comments & user profiles as JSON. No API key.
Social Media Web Scraping
2
google-ads
ai.adramp
Google Ads MCP server — manage campaigns, keywords, and metrics.
Marketing E-commerce & Retail
2
LemonadoOAuth
io.github.lemonadolabs
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Marketing Research & Data Databases
3
Reddit A
io.github.pipeworx-io
Reddit MCP — public Reddit data via JSON endpoints (no auth required)
Social Media Search Open Data
4

Related MCP Servers

facebook-ads-mcp-server
Marketing Social Media
HeroBrian389
A
license
Not graded
quality
D
maintenance
MCP server for Meta/Facebook Marketing API allowing you to view and manage ad accounts, campaigns, ad sets, ads, and creatives, as well as fetch insights and upload ad images.
Updated 7 months ago (2026-02-26 19:06 UTC)
MIT
mcp-reddit-ads
Marketing Social Media
mharnett
A
license
A
quality
A
maintenance
MCP server for Reddit Ads API v3 enabling campaign management, ad creation, performance reporting, and audience targeting through Claude.
Updated 12 days ago (2026-09-09 04:29 UTC)
10
52 npm
3
MIT
reddit-mcp
Social Media Search
EmptyMind4
A
license
Not graded
quality
C
maintenance
MCP server for interacting with Reddit via OAuth, with tiered tools for reading, writing, and moderation actions.
Updated 2 months ago (2026-08-01 15:09 UTC)
MIT
@sylvia/reddit-mcp
Social Media Search Open Data
c1nn3r
A
license
Not graded
quality
B
maintenance
MCP server for Reddit data — subreddits, users, search, live comments. No OAuth required.
Updated 2 months ago (2026-08-04 16:45 UTC)
MIT