mcp-reddit-ads
This Reddit Ads MCP server, in its current read-only schema, lets you inspect ad accounts, campaigns, ad groups, ads, performance reporting, and targeting options.
Verify API connectivity and get account health, including active campaign count.
List all accessible Reddit ad accounts.
List campaigns, ad groups, and ads, optionally filtering by campaign or ad group.
Get aggregated performance reports with selectable metrics, date ranges, and breakdowns such as date, country, region, community, placement, and device OS.
Get daily performance for the last N days.
Search subreddits for targeting.
List interest categories for targeting.
Search geographic targeting options such as countries and regions.
Note: create/update/pause/enable tools are not exposed in this schema; the README says mutating tools require
REDDIT_ADS_MCP_WRITE=true.
Provides tools for managing Reddit Ads campaigns, ad groups, ads, performance reporting, and audience targeting via the Reddit Ads API.
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., "@mcp-reddit-ads show me my active campaigns"
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.
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-adsThe 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-adsOr clone the repository:
git clone https://github.com/mharnett/mcp-reddit-ads.git
cd mcp-reddit-ads
npm install
npm run buildConfiguration
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 readscopes
2. Environment Variables
Set credentials via environment variables:
Variable | Description |
| OAuth app client ID |
| OAuth app client secret |
| OAuth refresh token with ads scopes |
| Set to |
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 |
| Get account info and verify API connectivity |
| List all ad accounts accessible to the authenticated user |
Read
Tool | Description |
| List campaigns with optional status filter |
| List ad groups for a campaign |
| List ads for an ad group |
| Aggregated performance metrics for campaigns/ad groups/ads |
| Day-by-day performance breakdown |
Write: Campaigns
Tool | Description |
| Create a new campaign (PAUSED by default) |
| Update campaign name, budget, objective, or status |
Write: Ad Groups
Tool | Description |
| Create a new ad group with targeting (PAUSED by default) |
| Update ad group bid, targeting, or status |
Write: Ads
Tool | Description |
| Create a new ad with headline, body, URL, and media (PAUSED by default) |
| Update ad creative or status |
Bulk Operations
Tool | Description |
| Pause multiple campaigns, ad groups, or ads at once |
| Enable multiple campaigns, ad groups, or ads at once |
Targeting
Tool | Description |
| Search for subreddits by keyword for targeting |
| List available interest categories for targeting |
| 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
ACTIVEto go live.Report metrics default to the set configured in
config.jsonbut 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 toolsreddit_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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Reddit Ads MCP server: run Reddit campaigns, ad groups, ads and reports from AI.
Reddit Ads MCP server: 9 tools for subreddit reports, targeting, diagnosis. Read-only by default.
Hosted Meta Ads MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Meta Ads MCP server: run Facebook and Instagram campaigns, ad sets, ads and reports from AI.
Related MCP Servers
- FlicenseBqualityDmaintenanceAn MCP server that connects Claude to the LinkedIn Ads API for natural-language control over campaign management, audience targeting, creative uploads, analytics, and account auditing.37-
- AlicenseAqualityDmaintenanceMCP server to manage Meta Ads (Facebook/Instagram) campaigns, ad sets, insights, and audiences from Claude Code using natural language.9MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for Google Ads campaign reporting and management via Claude, enabling GAQL queries, performance metrics, and campaign modifications.-
- AlicenseBqualityDmaintenanceA 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.6MIT