Skip to main content
Glama
mcp-reddit-ads

mcp-reddit-ads

by mharnett

mcp-reddit-ads

MCP server for Reddit Ads API v3 -- campaign management, ad creation, performance reporting, and audience targeting via Claude.

Quick install

Claude Code, one line (replace the placeholder values with your own; see Configuration for how to get them):

claude mcp add --env REDDIT_CLIENT_ID=YOUR_CLIENT_ID --env REDDIT_CLIENT_SECRET=YOUR_CLIENT_SECRET --env REDDIT_REFRESH_TOKEN=YOUR_REFRESH_TOKEN --transport stdio mcp-reddit-ads -- npx -y mcp-reddit-ads

The server starts read-only. Add --env REDDIT_ADS_MCP_WRITE=true to expose the tools that change an account; new items are always created PAUSED.

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), then fully quit and restart Claude Desktop:

{
  "mcpServers": {
    "mcp-reddit-ads": {
      "command": "npx",
      "args": ["-y", "mcp-reddit-ads"],
      "env": {
        "REDDIT_CLIENT_ID": "YOUR_CLIENT_ID",
        "REDDIT_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "REDDIT_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
      }
    }
  }
}

Add this to ~/.codex/config.toml:

[mcp_servers.mcp-reddit-ads]
command = "npx"
args = ["-y", "mcp-reddit-ads"]

[mcp_servers.mcp-reddit-ads.env]
REDDIT_CLIENT_ID = "YOUR_CLIENT_ID"
REDDIT_CLIENT_SECRET = "YOUR_CLIENT_SECRET"
REDDIT_REFRESH_TOKEN = "YOUR_REFRESH_TOKEN"

Related MCP server: meta-ads-mcp

Features

  • 18 tools covering full CRUD for campaigns, ad groups, and ads

  • Performance reports with daily breakdowns

  • Subreddit, interest, and geographic targeting

  • Bulk pause/enable operations

  • Safe by default: all new entities created in PAUSED status

  • Budget inputs in dollars (auto-converts to Reddit's microcurrency format)

Installation

npm install mcp-reddit-ads

Or clone the repository:

git clone https://github.com/mharnett/mcp-reddit-ads.git
cd mcp-reddit-ads
npm install
npm run build

Configuration

Security: Never share your .mcp.json file or commit it to git -- it may contain API credentials. Add .mcp.json to your .gitignore.

1. Reddit OAuth App

Create a Reddit OAuth app at reddit.com/prefs/apps:

  • Select "script" type

  • Note the client ID and client secret

  • Obtain a refresh token with adsread adsedit read scopes

2. Environment Variables

Set credentials via environment variables:

Variable

Description

REDDIT_CLIENT_ID

OAuth app client ID

REDDIT_CLIENT_SECRET

OAuth app client secret

REDDIT_REFRESH_TOKEN

OAuth refresh token with ads scopes

REDDIT_ADS_MCP_WRITE

Set to true to enable mutating tools (create/update/pause/enable). Unset = read-only (default).

Read-only by default

As of v1.1.0 the MCP starts in read-only mode. The 10 read/report/targeting tools are always exposed, but the 8 mutating tools (create/update campaigns, ad groups, ads, and bulk pause/enable) are hidden from the tool list and refused at call time unless REDDIT_ADS_MCP_WRITE=true is set in the server's environment. This guards against a casual chat message accidentally mutating live ad spend. Enable writes deliberately, for the sessions where you actually intend to ship changes.

3. Config File

Copy config.example.json to config.json and fill in defaults:

{
  "reddit_api": {
    "base_url": "https://ads-api.reddit.com/api/v3",
    "auth": {
      "client_id": "",
      "client_secret": "",
      "refresh_token": "",
      "user_agent": "reddit-ad-mcp/1.0"
    }
  },
  "defaults": {
    "account_id": "",
    "business_id": "",
    "report_metrics": ["impressions", "clicks", "spend", "ctr", "cpc", "ecpm"],
    "date_range_days": 7
  }
}

Environment variables take precedence over config file values.

Usage

Claude Code (.mcp.json)

{
  "mcpServers": {
    "reddit-ads": {
      "command": "node",
      "args": ["/path/to/mcp-reddit-ads/dist/index.js"],
      "env": {
        "REDDIT_CLIENT_ID": "$(security find-generic-password -a reddit-ads-mcp -s REDDIT_CLIENT_ID -w)",
        "REDDIT_CLIENT_SECRET": "$(security find-generic-password -a reddit-ads-mcp -s REDDIT_CLIENT_SECRET -w)",
        "REDDIT_REFRESH_TOKEN": "$(security find-generic-password -a reddit-ads-mcp -s REDDIT_REFRESH_TOKEN -w)"
      }
    }
  }
}

Claude Desktop: Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Tools

Context

Tool

Description

reddit_ads_get_client_context

Get account info and verify API connectivity

reddit_ads_get_accounts

List all ad accounts accessible to the authenticated user

Read

Tool

Description

reddit_ads_get_campaigns

List campaigns with optional status filter

reddit_ads_get_ad_groups

List ad groups for a campaign

reddit_ads_get_ads

List ads for an ad group

reddit_ads_get_performance_report

Aggregated performance metrics for campaigns/ad groups/ads

reddit_ads_get_daily_performance

Day-by-day performance breakdown

Write: Campaigns

Tool

Description

reddit_ads_create_campaign

Create a new campaign (PAUSED by default)

reddit_ads_update_campaign

Update campaign name, budget, objective, or status

Write: Ad Groups

Tool

Description

reddit_ads_create_ad_group

Create a new ad group with targeting (PAUSED by default)

reddit_ads_update_ad_group

Update ad group bid, targeting, or status

Write: Ads

Tool

Description

reddit_ads_create_ad

Create a new ad with headline, body, URL, and media (PAUSED by default)

reddit_ads_update_ad

Update ad creative or status

Bulk Operations

Tool

Description

reddit_ads_pause_items

Pause multiple campaigns, ad groups, or ads at once

reddit_ads_enable_items

Enable multiple campaigns, ad groups, or ads at once

Targeting

Tool

Description

reddit_ads_search_subreddits

Search for subreddits by keyword for targeting

reddit_ads_get_interest_categories

List available interest categories for targeting

reddit_ads_search_geo_targets

Search for geographic targeting options (countries, regions, metros)

Key Conventions

  • Spend values are returned from the API in microcurrency (1 dollar = 1,000,000 microcurrency units). Divide by 1,000,000 to get dollar amounts. Budget inputs accept dollars and auto-convert.

  • Dates and times use ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).

  • New entities default to PAUSED status. Explicitly set status to ACTIVE to go live.

  • Report metrics default to the set configured in config.json but can be overridden per request.

Architecture

  • Resilience: Uses cockatiel for retry policies and circuit breaking on API calls

  • Logging: Structured logging via pino

  • Response truncation: Large API responses are truncated at 200KB to stay within MCP message limits

  • Auth: OAuth 2.0 refresh token flow with automatic access token renewal

License

MIT -- see LICENSE.

Author

Built by Mark Harnett / drak-marketing.

Available Tools

10 tools
reddit_ads_get_accountsA

List all Reddit ad accounts accessible to this user.

Inputs: no named parameters.

reddit_ads_get_ad_groupsB

List ad groups for a Reddit ad account, optionally filtered by campaign.

Inputs: account_id, campaign_id.

reddit_ads_get_adsB

List ads for a Reddit ad account, optionally filtered by ad group.

Inputs: account_id, ad_group_id.

reddit_ads_get_campaignsB

List all campaigns for a Reddit ad account.

Inputs: account_id.

reddit_ads_get_client_contextA

Get a quick overview and health status of the Reddit Ads account. Returns account info and active campaign count.

Inputs: account_id.

reddit_ads_get_daily_performanceB

Get daily performance breakdown for the last N days. Convenience tool with date breakdown.

Inputs: days, account_id.

reddit_ads_get_interest_categoriesB

Get available interest categories for ad group targeting.

Inputs: no named parameters.

reddit_ads_get_performance_reportA

Get a performance report for Reddit ads. Spend values are in microcurrency (divide by 1,000,000 for dollars).

Inputs: fields, end_date, account_id, breakdowns, +1 more.

reddit_ads_search_geo_targetsA

Search geographic targeting options (countries, regions).

Inputs: query.

reddit_ads_search_subredditsA

Search for subreddits to use as targeting in ad groups.

Inputs: query (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action, such as accounts, ad groups, ads, campaigns, performance, and targeting options. There is no overlap in functionality, and descriptions clearly differentiate them.

    Naming Consistency4/5

    All tools share the 'reddit_ads_' prefix, and most use 'get_' followed by the resource name. Two tools use 'search_' instead, and there is a slight inconsistency between 'get_daily_performance' and 'get_performance_report', but the overall pattern is clear and predictable.

    Tool Count5/5

    With 10 tools, the server covers the main areas of Reddit Ads: account info, campaign/ad group/ad listing, performance reports, and targeting options. The number feels appropriate for the scope without being overwhelming or too sparse.

    Completeness2/5

    The tool set is entirely read-only, offering only retrieval operations. Missing capabilities for creating, updating, or deleting campaigns, ad groups, or ads, which are essential for full ads management. This is a significant gap for a tool advertised as a Reddit Ads server.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server to manage Meta Ads (Facebook/Instagram) campaigns, ad sets, insights, and audiences from Claude Code using natural language.
      9
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Google Ads campaign reporting and management via Claude, enabling GAQL queries, performance metrics, and campaign modifications.
      -
    • A
      license
      B
      quality
      D
      maintenance
      A self-hosted MCP server for the Reddit Ads API v3, enabling reading ad accounts, campaigns, ad groups, ads, and performance reports, with optional write support for pausing/activating, budgeting, patching, and creating entities.
      6
      MIT