{
  "markdown": "# mcp-reddit-ads\n\nMCP server for Reddit Ads API v3 -- campaign management, ad creation, performance reporting, and audience targeting via Claude.\n\n## Features\n\n- **18 tools** covering full CRUD for campaigns, ad groups, and ads\n- Performance reports with daily breakdowns\n- Subreddit, interest, and geographic targeting\n- Bulk pause/enable operations\n- Safe by default: all new entities created in PAUSED status\n- Budget inputs in dollars (auto-converts to Reddit's microcurrency format)\n\n## Installation\n\n```bash\nnpm install mcp-reddit-ads\n```\n\nOr clone the repository:\n\n```bash\ngit clone https://github.com/mharnett/mcp-reddit-ads.git\ncd mcp-reddit-ads\nnpm install\nnpm run build\n```\n\n## Configuration\n\n**Security:** Never share your `.mcp.json` file or commit it to git -- it may contain API credentials. Add `.mcp.json` to your `.gitignore`.\n\n### 1. Reddit OAuth App\n\nCreate a Reddit OAuth app at [reddit.com/prefs/apps](https://www.reddit.com/prefs/apps):\n\n- Select \"script\" type\n- Note the client ID and client secret\n- Obtain a refresh token with `adsread adsedit read` scopes\n\n### 2. Environment Variables\n\nSet credentials via environment variables:\n\n| Variable | Description |\n|---|---|\n| `REDDIT_CLIENT_ID` | OAuth app client ID |\n| `REDDIT_CLIENT_SECRET` | OAuth app client secret |\n| `REDDIT_REFRESH_TOKEN` | OAuth refresh token with ads scopes |\n| `REDDIT_ADS_MCP_WRITE` | Set to `true` to enable mutating tools (create/update/pause/enable). Unset = read-only (default). |\n\n### Read-only by default\n\nAs 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.\n\n### 3. Config File\n\nCopy `config.example.json` to `config.json` and fill in defaults:\n\n```json\n{\n  \"reddit_api\": {\n    \"base_url\": \"https://ads-api.reddit.com/api/v3\",\n    \"auth\": {\n      \"client_id\": \"\",\n      \"client_secret\": \"\",\n      \"refresh_token\": \"\",\n      \"user_agent\": \"reddit-ad-mcp/1.0\"\n    }\n  },\n  \"defaults\": {\n    \"account_id\": \"\",\n    \"business_id\": \"\",\n    \"report_metrics\": [\"impressions\", \"clicks\", \"spend\", \"ctr\", \"cpc\", \"ecpm\"],\n    \"date_range_days\": 7\n  }\n}\n```\n\nEnvironment variables take precedence over config file values.\n\n## Usage\n\n### Claude Code (.mcp.json)\n\n```json\n{\n  \"mcpServers\": {\n    \"reddit-ads\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-reddit-ads/dist/index.js\"],\n      \"env\": {\n        \"REDDIT_CLIENT_ID\": \"$(security find-generic-password -a reddit-ads-mcp -s REDDIT_CLIENT_ID -w)\",\n        \"REDDIT_CLIENT_SECRET\": \"$(security find-generic-password -a reddit-ads-mcp -s REDDIT_CLIENT_SECRET -w)\",\n        \"REDDIT_REFRESH_TOKEN\": \"$(security find-generic-password -a reddit-ads-mcp -s REDDIT_REFRESH_TOKEN -w)\"\n      }\n    }\n  }\n}\n```\n\n**Claude Desktop:** Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows).\n\n## Tools\n\n### Context\n\n| Tool | Description |\n|---|---|\n| `reddit_ads_get_client_context` | Get account info and verify API connectivity |\n| `reddit_ads_get_accounts` | List all ad accounts accessible to the authenticated user |\n\n### Read\n\n| Tool | Description |\n|---|---|\n| `reddit_ads_get_campaigns` | List campaigns with optional status filter |\n| `reddit_ads_get_ad_groups` | List ad groups for a campaign |\n| `reddit_ads_get_ads` | List ads for an ad group |\n| `reddit_ads_get_performance_report` | Aggregated performance metrics for campaigns/ad groups/ads |\n| `reddit_ads_get_daily_performance` | Day-by-day performance breakdown |\n\n### Write: Campaigns\n\n| Tool | Description |\n|---|---|\n| `reddit_ads_create_campaign` | Create a new campaign (PAUSED by default) |\n| `reddit_ads_update_campaign` | Update campaign name, budget, objective, or status |\n\n### Write: Ad Groups\n\n| Tool | Description |\n|---|---|\n| `reddit_ads_create_ad_group` | Create a new ad group with targeting (PAUSED by default) |\n| `reddit_ads_update_ad_group` | Update ad group bid, targeting, or status |\n\n### Write: Ads\n\n| Tool | Description |\n|---|---|\n| `reddit_ads_create_ad` | Create a new ad with headline, body, URL, and media (PAUSED by default) |\n| `reddit_ads_update_ad` | Update ad creative or status |\n\n### Bulk Operations\n\n| Tool | Description |\n|---|---|\n| `reddit_ads_pause_items` | Pause multiple campaigns, ad groups, or ads at once |\n| `reddit_ads_enable_items` | Enable multiple campaigns, ad groups, or ads at once |\n\n### Targeting\n\n| Tool | Description |\n|---|---|\n| `reddit_ads_search_subreddits` | Search for subreddits by keyword for targeting |\n| `reddit_ads_get_interest_categories` | List available interest categories for targeting |\n| `reddit_ads_search_geo_targets` | Search for geographic targeting options (countries, regions, metros) |\n\n## Key Conventions\n\n- **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.\n- **Dates and times** use ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`).\n- **New entities default to PAUSED** status. Explicitly set status to `ACTIVE` to go live.\n- **Report metrics** default to the set configured in `config.json` but can be overridden per request.\n\n## Architecture\n\n- **Resilience**: Uses [cockatiel](https://github.com/connor4312/cockatiel) for retry policies and circuit breaking on API calls\n- **Logging**: Structured logging via [pino](https://github.com/pinojs/pino)\n- **Response truncation**: Large API responses are truncated at 200KB to stay within MCP message limits\n- **Auth**: OAuth 2.0 refresh token flow with automatic access token renewal\n\n## License\n\nMIT -- see [LICENSE](LICENSE).\n\n## Author\n\nBuilt by Mark Harnett / [drak-marketing](https://github.com/drak-marketing).\n",
  "bytes": 6121,
  "sha": "360f92c04289a565a689214f881a308d1ba3959749aae1edf4f358dd8f9d2a41",
  "repo_slug": "mharnett/mcp-reddit-ads",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mharnett_reddit_ads_20e3bdd1/readme"
}