mcp-reddit-ads

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

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/drak-marketing/mcp-reddit-ads.git
cd mcp-reddit-ads
npm install
npm run build

Configuration

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 |

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)"
      }
    }
  }
}

Tools

Context

| Tool | Description | |---|---| | get_client_context | Get account info and verify API connectivity | | get_accounts | List all ad accounts accessible to the authenticated user |

Read

| Tool | Description | |---|---| | get_campaigns | List campaigns with optional status filter | | get_ad_groups | List ad groups for a campaign | | get_ads | List ads for an ad group | | get_performance_report | Aggregated performance metrics for campaigns/ad groups/ads | | get_daily_performance | Day-by-day performance breakdown |

Write: Campaigns

| Tool | Description | |---|---| | create_campaign | Create a new campaign (PAUSED by default) | | update_campaign | Update campaign name, budget, objective, or status |

Write: Ad Groups

| Tool | Description | |---|---| | create_ad_group | Create a new ad group with targeting (PAUSED by default) | | update_ad_group | Update ad group bid, targeting, or status |

Write: Ads

| Tool | Description | |---|---| | create_ad | Create a new ad with headline, body, URL, and media (PAUSED by default) | | update_ad | Update ad creative or status |

Bulk Operations

| Tool | Description | |---|---| | pause_items | Pause multiple campaigns, ad groups, or ads at once | | enable_items | Enable multiple campaigns, ad groups, or ads at once |

Targeting

| Tool | Description | |---|---| | search_subreddits | Search for subreddits by keyword for targeting | | get_interest_categories | List available interest categories for targeting | | search_geo_targets | Search for geographic targeting options (countries, regions, metros) |

Key Conventions

• **Spend valu

... View full README on GitHub