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

reddit-ads

Quick Install