mcp-reddit-ads 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 drak-marketing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# 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
+
+```bash
+npm install mcp-reddit-ads
+```
+
+Or clone the repository:
+
+```bash
+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](https://www.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:
+
+```json
+{
+  "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)
+
+```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](https://github.com/connor4312/cockatiel) for retry policies and circuit breaking on API calls
+- **Logging**: Structured logging via [pino](https://github.com/pinojs/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](LICENSE).
+
+## Author
+
+Built by Mark Harnett / [drak-marketing](https://github.com/drak-marketing).

package/config.example.json

@@ -0,0 +1,17 @@
+{
+  "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
+  }
+}

package/dist/build-info.json

@@ -0,0 +1 @@
+{"sha":"c18ff2d","builtAt":"2026-04-03T23:26:48.972Z"}

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+export declare class RedditAdsAuthError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare class RedditAdsRateLimitError extends Error {
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number, cause?: unknown);
+}
+export declare class RedditAdsServiceError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare function validateCredentials(): {
+    valid: boolean;
+    missing: string[];
+};
+export declare function classifyError(error: any): Error;

package/dist/errors.js

@@ -0,0 +1,60 @@
+// ============================================
+// TYPED ERRORS
+// ============================================
+export class RedditAdsAuthError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "RedditAdsAuthError";
+    }
+}
+export class RedditAdsRateLimitError extends Error {
+    retryAfterMs;
+    constructor(retryAfterMs, cause) {
+        super(`Rate limited, retry after ${retryAfterMs}ms`);
+        this.retryAfterMs = retryAfterMs;
+        this.name = "RedditAdsRateLimitError";
+        this.cause = cause;
+    }
+}
+export class RedditAdsServiceError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "RedditAdsServiceError";
+    }
+}
+// ============================================
+// STARTUP CREDENTIAL VALIDATION
+// ============================================
+export function validateCredentials() {
+    const required = [
+        "REDDIT_CLIENT_ID",
+        "REDDIT_CLIENT_SECRET",
+        "REDDIT_REFRESH_TOKEN",
+    ];
+    const missing = required.filter((key) => !process.env[key] || process.env[key].trim() === "");
+    return { valid: missing.length === 0, missing };
+}
+export function classifyError(error) {
+    const message = error?.message || String(error);
+    const status = error?.status;
+    if (status === 401 ||
+        status === 403 ||
+        message.includes("invalid_grant") ||
+        message.includes("OAuth") ||
+        message.includes("Unauthorized") ||
+        message.includes("Forbidden")) {
+        return new RedditAdsAuthError(`Auth failed: ${message}. Refresh token may be expired. Update REDDIT_REFRESH_TOKEN in Keychain.`, error);
+    }
+    if (status === 429 || message.includes("rate limit") || message.includes("Rate limit")) {
+        const retryMs = error?.retryAfterMs || 60_000;
+        return new RedditAdsRateLimitError(retryMs, error);
+    }
+    if (status >= 500 || message.includes("Internal Server Error") || message.includes("Service Unavailable")) {
+        return new RedditAdsServiceError(`Reddit API server error: ${message}`, error);
+    }
+    return error;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,499 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { RedditAdsAuthError, RedditAdsRateLimitError, RedditAdsServiceError, classifyError, validateCredentials, } from "./errors.js";
+import { tools } from "./tools.js";
+import { withResilience, safeResponse, logger } from "./resilience.js";
+// Log build fingerprint at startup
+try {
+    const __buildInfoDir = dirname(new URL(import.meta.url).pathname);
+    const buildInfo = JSON.parse(readFileSync(join(__buildInfoDir, "build-info.json"), "utf-8"));
+    console.error(`[build] SHA: ${buildInfo.sha} (${buildInfo.builtAt})`);
+}
+catch {
+    // build-info.json not present (dev mode)
+}
+function loadConfig() {
+    const configPath = join(dirname(new URL(import.meta.url).pathname), "..", "config.json");
+    if (!existsSync(configPath)) {
+        throw new Error(`Config file not found at ${configPath}. Copy config.example.json to config.json.`);
+    }
+    const config = JSON.parse(readFileSync(configPath, "utf-8"));
+    // Environment overrides
+    if (process.env.REDDIT_CLIENT_ID)
+        config.reddit_api.auth.client_id = process.env.REDDIT_CLIENT_ID;
+    if (process.env.REDDIT_CLIENT_SECRET)
+        config.reddit_api.auth.client_secret = process.env.REDDIT_CLIENT_SECRET;
+    if (process.env.REDDIT_REFRESH_TOKEN)
+        config.reddit_api.auth.refresh_token = process.env.REDDIT_REFRESH_TOKEN;
+    if (process.env.REDDIT_ACCOUNT_ID)
+        config.defaults.account_id = process.env.REDDIT_ACCOUNT_ID;
+    return config;
+}
+// ============================================
+// DATE HELPERS
+// ============================================
+function getDateRange(days) {
+    const end = new Date();
+    const start = new Date(end);
+    start.setDate(start.getDate() - days);
+    return {
+        startDate: start.toISOString().slice(0, 10),
+        endDate: end.toISOString().slice(0, 10),
+    };
+}
+// ============================================
+// REDDIT ADS API CLIENT
+// ============================================
+class RedditAdsManager {
+    config;
+    accessToken = null;
+    tokenExpiry = 0;
+    constructor(config) {
+        this.config = config;
+        const creds = validateCredentials();
+        if (!creds.valid) {
+            const msg = `[STARTUP ERROR] Missing required credentials: ${creds.missing.join(", ")}. MCP will not function. Check run-mcp.sh and Keychain entries.`;
+            console.error(msg);
+            throw new RedditAdsAuthError(msg);
+        }
+        console.error("[startup] Credentials validated: all required env vars present");
+    }
+    async getAccessToken() {
+        if (this.accessToken && Date.now() < this.tokenExpiry) {
+            return this.accessToken;
+        }
+        const auth = this.config.reddit_api.auth;
+        const credentials = Buffer.from(`${auth.client_id}:${auth.client_secret}`).toString("base64");
+        const resp = await fetch("https://www.reddit.com/api/v1/access_token", {
+            method: "POST",
+            headers: {
+                "Authorization": `Basic ${credentials}`,
+                "User-Agent": auth.user_agent,
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: new URLSearchParams({
+                grant_type: "refresh_token",
+                refresh_token: auth.refresh_token,
+            }).toString(),
+        });
+        if (!resp.ok) {
+            const text = await resp.text();
+            const error = new Error(`OAuth token refresh failed: ${resp.status} ${text}`);
+            error.status = resp.status;
+            throw classifyError(error);
+        }
+        const data = await resp.json();
+        this.accessToken = data.access_token;
+        this.tokenExpiry = Date.now() + ((data.expires_in || 3600) - 60) * 1000;
+        return this.accessToken;
+    }
+    async apiCall(method, path, options) {
+        const token = await this.getAccessToken();
+        const auth = this.config.reddit_api.auth;
+        let url = `${this.config.reddit_api.base_url}${path}`;
+        if (options?.params) {
+            const qs = new URLSearchParams(options.params).toString();
+            if (qs)
+                url += `?${qs}`;
+        }
+        const resp = await fetch(url, {
+            method,
+            headers: {
+                "Authorization": `Bearer ${token}`,
+                "User-Agent": auth.user_agent,
+                "Content-Type": "application/json",
+            },
+            body: options?.body ? JSON.stringify(options.body) : undefined,
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (!resp.ok) {
+            const text = await resp.text();
+            const error = new Error(`Reddit API error: ${resp.status} ${text}`);
+            error.status = resp.status;
+            throw classifyError(error);
+        }
+        return resp.json();
+    }
+    resolveAccountId(accountId) {
+        if (accountId)
+            return accountId;
+        if (this.config.defaults.account_id)
+            return this.config.defaults.account_id;
+        throw new Error("No account_id provided and no default configured");
+    }
+    // ── Read operations ──────────────────────────────────────────────
+    async getMe() {
+        return withResilience(() => this.apiCall("GET", "/me"), "getMe");
+    }
+    async getAccounts() {
+        return withResilience(async () => {
+            const businesses = await this.apiCall("GET", "/me/businesses");
+            if (businesses?.data?.length > 0) {
+                const bizId = businesses.data[0].id;
+                return this.apiCall("GET", `/businesses/${bizId}/ad_accounts`);
+            }
+            return { data: [], error: "No businesses found" };
+        }, "getAccounts");
+    }
+    async getCampaigns(accountId) {
+        return withResilience(() => this.apiCall("GET", `/ad_accounts/${accountId}/campaigns`), "getCampaigns");
+    }
+    async getAdGroups(accountId, campaignId) {
+        const params = {};
+        if (campaignId)
+            params.campaign_id = campaignId;
+        return withResilience(() => this.apiCall("GET", `/ad_accounts/${accountId}/ad_groups`, { params }), "getAdGroups");
+    }
+    async getAds(accountId, adGroupId) {
+        const params = {};
+        if (adGroupId)
+            params.ad_group_id = adGroupId;
+        return withResilience(() => this.apiCall("GET", `/ad_accounts/${accountId}/ads`, { params }), "getAds");
+    }
+    async getReport(accountId, options) {
+        const fields = options.fields || this.config.defaults.report_metrics;
+        let startDate = options.startDate;
+        let endDate = options.endDate;
+        // Ensure ISO 8601 format
+        if (!startDate.includes("T"))
+            startDate = `${startDate}T00:00:00Z`;
+        if (!endDate.includes("T"))
+            endDate = `${endDate}T00:00:00Z`;
+        const reportData = {
+            starts_at: startDate,
+            ends_at: endDate,
+            fields,
+        };
+        if (options.breakdowns) {
+            reportData.breakdowns = options.breakdowns;
+        }
+        return withResilience(() => this.apiCall("POST", `/ad_accounts/${accountId}/reports`, { body: { data: reportData } }), "getReport");
+    }
+    // ── Write operations ─────────────────────────────────────────────
+    async createCampaign(accountId, data) {
+        const body = {
+            name: data.name,
+            objective: data.objective,
+            goal_type: "DAILY_SPEND",
+            goal_value: data.dailyBudgetMicro,
+            start_time: data.startTime,
+            configured_status: data.configuredStatus || "PAUSED",
+        };
+        if (data.endTime)
+            body.end_time = data.endTime;
+        return withResilience(() => this.apiCall("POST", `/ad_accounts/${accountId}/campaigns`, { body: { data: body } }), "createCampaign");
+    }
+    async updateCampaign(campaignId, updates) {
+        return withResilience(() => this.apiCall("PUT", `/campaigns/${campaignId}`, { body: { data: updates } }), "updateCampaign");
+    }
+    async createAdGroup(accountId, data) {
+        const body = {
+            campaign_id: data.campaignId,
+            name: data.name,
+            bid_type: data.bidStrategy || "CPM",
+            bid_value: data.bidMicro,
+            start_time: data.startTime,
+            configured_status: data.configuredStatus || "PAUSED",
+        };
+        if (data.endTime)
+            body.end_time = data.endTime;
+        if (data.target)
+            body.targeting = data.target;
+        if (data.optimizationGoal)
+            body.optimization_goal = data.optimizationGoal;
+        return withResilience(() => this.apiCall("POST", `/ad_accounts/${accountId}/ad_groups`, { body: { data: body } }), "createAdGroup");
+    }
+    async updateAdGroup(adGroupId, updates) {
+        return withResilience(() => this.apiCall("PUT", `/ad_groups/${adGroupId}`, { body: { data: updates } }), "updateAdGroup");
+    }
+    async createAd(accountId, data) {
+        const adData = {
+            ad_group_id: data.adGroupId,
+            name: data.name,
+            configured_status: data.configuredStatus || "PAUSED",
+        };
+        if (data.headline)
+            adData.headline = data.headline;
+        if (data.clickUrl)
+            adData.click_url = data.clickUrl;
+        if (data.thumbnailUrl)
+            adData.thumbnail_url = data.thumbnailUrl;
+        if (data.bodyText)
+            adData.body = data.bodyText;
+        if (data.callToAction)
+            adData.call_to_action = data.callToAction;
+        if (data.creativeType)
+            adData.creative_type = data.creativeType;
+        if (data.videoUrl)
+            adData.video_url = data.videoUrl;
+        if (data.postUrl)
+            adData.post_url = data.postUrl;
+        return withResilience(() => this.apiCall("POST", `/ad_accounts/${accountId}/ads`, { body: { data: adData } }), "createAd");
+    }
+    async updateAd(adId, updates) {
+        return withResilience(() => this.apiCall("PUT", `/ads/${adId}`, { body: { data: updates } }), "updateAd");
+    }
+    // ── Targeting ────────────────────────────────────────────────────
+    async searchSubreddits(query) {
+        return withResilience(() => this.apiCall("GET", "/targeting/subreddits", { params: { query } }), "searchSubreddits");
+    }
+    async getInterestCategories() {
+        return withResilience(() => this.apiCall("GET", "/targeting/interests"), "getInterestCategories");
+    }
+    async searchGeoTargets(query) {
+        const params = {};
+        if (query)
+            params.query = query;
+        return withResilience(() => this.apiCall("GET", "/targeting/geos", { params }), "searchGeoTargets");
+    }
+    getDefaultAccountId() {
+        return this.config.defaults.account_id || null;
+    }
+}
+// ============================================
+// MCP SERVER
+// ============================================
+const config = loadConfig();
+const adsManager = new RedditAdsManager(config);
+const server = new Server({ name: "mcp-reddit-ads", version: "1.0.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const ok = (data) => ({
+        content: [{ type: "text", text: JSON.stringify(safeResponse(data, name), null, 2) }],
+    });
+    try {
+        const accountId = () => {
+            const id = args?.account_id;
+            if (id)
+                return id;
+            const def = adsManager.getDefaultAccountId();
+            if (def)
+                return def;
+            throw new Error("No account_id provided and no default configured");
+        };
+        switch (name) {
+            // ── Context ──
+            case "reddit_ads_get_client_context": {
+                const acctId = accountId();
+                const me = await adsManager.getMe();
+                const campaigns = await adsManager.getCampaigns(acctId);
+                const campaignData = (campaigns?.data || []);
+                const active = campaignData.filter((c) => c.configured_status === "ACTIVE");
+                return ok({
+                    account_id: acctId,
+                    user: me?.data || {},
+                    total_campaigns: campaignData.length,
+                    active_campaigns: active.length,
+                    active_campaign_names: active.map((c) => c.name),
+                    status: "connected",
+                });
+            }
+            // ── Read ──
+            case "reddit_ads_get_accounts":
+                return ok(await adsManager.getAccounts());
+            case "reddit_ads_get_campaigns":
+                return ok(await adsManager.getCampaigns(accountId()));
+            case "reddit_ads_get_ad_groups":
+                return ok(await adsManager.getAdGroups(accountId(), args?.campaign_id));
+            case "reddit_ads_get_ads":
+                return ok(await adsManager.getAds(accountId(), args?.ad_group_id));
+            case "reddit_ads_get_performance_report": {
+                const acctId = accountId();
+                const { startDate, endDate } = args?.start_date && args?.end_date
+                    ? { startDate: args.start_date, endDate: args.end_date }
+                    : getDateRange(7);
+                return ok(await adsManager.getReport(acctId, {
+                    startDate,
+                    endDate,
+                    fields: args?.fields,
+                    breakdowns: args?.breakdowns,
+                }));
+            }
+            case "reddit_ads_get_daily_performance": {
+                const acctId = accountId();
+                const days = args?.days || 7;
+                const { startDate, endDate } = getDateRange(days);
+                return ok(await adsManager.getReport(acctId, {
+                    startDate,
+                    endDate,
+                    fields: ["impressions", "clicks", "spend", "ctr", "cpc"],
+                    breakdowns: ["date"],
+                }));
+            }
+            // ── Write: Campaigns ──
+            case "reddit_ads_create_campaign": {
+                const acctId = accountId();
+                const budgetMicro = Math.round(args?.daily_budget_dollars * 1_000_000);
+                return ok(await adsManager.createCampaign(acctId, {
+                    name: args?.name,
+                    objective: args?.objective,
+                    dailyBudgetMicro: budgetMicro,
+                    startTime: args?.start_time,
+                    endTime: args?.end_time,
+                    configuredStatus: args?.configured_status || "PAUSED",
+                }));
+            }
+            case "reddit_ads_update_campaign": {
+                const updates = {};
+                if (args?.name != null)
+                    updates.name = args.name;
+                if (args?.daily_budget_dollars != null)
+                    updates.daily_budget_micro = Math.round(args.daily_budget_dollars * 1_000_000);
+                if (args?.configured_status != null)
+                    updates.configured_status = args.configured_status;
+                if (args?.end_time != null)
+                    updates.end_time = args.end_time;
+                return ok(await adsManager.updateCampaign(args?.campaign_id, updates));
+            }
+            // ── Write: Ad Groups ──
+            case "reddit_ads_create_ad_group": {
+                const acctId = accountId();
+                const bidMicro = Math.round(args?.bid_dollars * 1_000_000);
+                const target = {};
+                if (args?.subreddit_names)
+                    target.communities = args.subreddit_names;
+                if (args?.interest_ids)
+                    target.interests = args.interest_ids;
+                if (args?.geo_country_codes)
+                    target.geos = args.geo_country_codes.map(c => ({ country: c }));
+                if (args?.device_types)
+                    target.devices = args.device_types;
+                return ok(await adsManager.createAdGroup(acctId, {
+                    campaignId: args?.campaign_id,
+                    name: args?.name,
+                    bidMicro,
+                    startTime: args?.start_time,
+                    endTime: args?.end_time,
+                    target: Object.keys(target).length > 0 ? target : undefined,
+                    bidStrategy: args?.bid_strategy || "CPM",
+                    configuredStatus: args?.configured_status || "PAUSED",
+                    optimizationGoal: args?.optimization_goal,
+                }));
+            }
+            case "reddit_ads_update_ad_group": {
+                const updates = {};
+                if (args?.name != null)
+                    updates.name = args.name;
+                if (args?.bid_dollars != null)
+                    updates.bid_micro = Math.round(args.bid_dollars * 1_000_000);
+                if (args?.configured_status != null)
+                    updates.configured_status = args.configured_status;
+                if (args?.end_time != null)
+                    updates.end_time = args.end_time;
+                return ok(await adsManager.updateAdGroup(args?.ad_group_id, updates));
+            }
+            // ── Write: Ads ──
+            case "reddit_ads_create_ad": {
+                const acctId = accountId();
+                return ok(await adsManager.createAd(acctId, {
+                    adGroupId: args?.ad_group_id,
+                    name: args?.name,
+                    headline: args?.headline,
+                    clickUrl: args?.click_url,
+                    thumbnailUrl: args?.thumbnail_url,
+                    bodyText: args?.body_text,
+                    callToAction: args?.call_to_action || "LEARN_MORE",
+                    configuredStatus: args?.configured_status || "PAUSED",
+                    creativeType: args?.creative_type || "IMAGE",
+                    videoUrl: args?.video_url,
+                    postUrl: args?.post_url,
+                }));
+            }
+            case "reddit_ads_update_ad": {
+                const updates = {};
+                if (args?.name != null)
+                    updates.name = args.name;
+                if (args?.headline != null)
+                    updates.headline = args.headline;
+                if (args?.click_url != null)
+                    updates.click_url = args.click_url;
+                if (args?.configured_status != null)
+                    updates.configured_status = args.configured_status;
+                if (args?.call_to_action != null)
+                    updates.call_to_action = args.call_to_action;
+                return ok(await adsManager.updateAd(args?.ad_id, updates));
+            }
+            // ── Bulk status ──
+            case "reddit_ads_pause_items":
+            case "reddit_ads_enable_items": {
+                const statusValue = name === "reddit_ads_pause_items" ? "PAUSED" : "ACTIVE";
+                const itemType = args?.item_type;
+                const itemIds = args?.item_ids;
+                const updateFn = {
+                    CAMPAIGN: (id, u) => adsManager.updateCampaign(id, u),
+                    AD_GROUP: (id, u) => adsManager.updateAdGroup(id, u),
+                    AD: (id, u) => adsManager.updateAd(id, u),
+                };
+                const fn = updateFn[itemType];
+                if (!fn)
+                    return ok({ error: `Invalid item_type: ${itemType}. Use CAMPAIGN, AD_GROUP, or AD.` });
+                const results = [];
+                for (const itemId of itemIds) {
+                    try {
+                        const result = await fn(itemId, { configured_status: statusValue });
+                        results.push({ id: itemId, status: statusValue.toLowerCase(), result });
+                    }
+                    catch (e) {
+                        results.push({ id: itemId, status: "error", error: e.message });
+                    }
+                }
+                return ok(results);
+            }
+            // ── Targeting ──
+            case "reddit_ads_search_subreddits":
+                return ok(await adsManager.searchSubreddits(args?.query));
+            case "reddit_ads_get_interest_categories":
+                return ok(await adsManager.getInterestCategories());
+            case "reddit_ads_search_geo_targets":
+                return ok(await adsManager.searchGeoTargets(args?.query));
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (rawError) {
+        const error = classifyError(rawError);
+        logger.error({ error_type: error.name, message: error.message }, "Tool call failed");
+        const response = {
+            error: true,
+            error_type: error.name,
+            message: error.message,
+        };
+        if (error instanceof RedditAdsAuthError) {
+            response.action_required = "Re-authenticate: refresh token may be expired. Run oauth_flow.py and update Keychain.";
+        }
+        else if (error instanceof RedditAdsRateLimitError) {
+            response.retry_after_ms = error.retryAfterMs;
+            response.action_required = `Rate limited. Retry after ${Math.ceil(error.retryAfterMs / 1000)} seconds.`;
+        }
+        else if (error instanceof RedditAdsServiceError) {
+            response.action_required = "Reddit API server error. This is transient - retry in a few minutes.";
+        }
+        else {
+            response.details = rawError.stack;
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    try {
+        const me = await adsManager.getMe();
+        console.error(`[startup] Auth verified: logged in as ${me?.data?.username || "unknown"}`);
+    }
+    catch (err) {
+        console.error(`[STARTUP WARNING] Auth check FAILED: ${err.message}`);
+        console.error(`[STARTUP WARNING] MCP will start but API calls may fail until auth is fixed.`);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[startup] MCP Reddit Ads server running");
+}
+main().catch(console.error);

package/dist/resilience.d.ts

@@ -0,0 +1,3 @@
+export declare const logger: import("pino").Logger<never>;
+export declare function safeResponse<T>(data: T, context: string): T;
+export declare function withResilience<T>(fn: () => Promise<T>, operationName: string): Promise<T>;

package/dist/resilience.js

@@ -0,0 +1,76 @@
+import { retry, circuitBreaker, wrap, handleAll, timeout, TimeoutStrategy, ExponentialBackoff, ConsecutiveBreaker, } from "cockatiel";
+import pino from "pino";
+// ============================================
+// LOGGER
+// ============================================
+export const logger = pino({
+    level: process.env.LOG_LEVEL || "info",
+    ...(process.env.NODE_ENV !== "test" && {
+        transport: {
+            target: "pino-pretty",
+            options: {
+                colorize: true,
+                singleLine: true,
+                translateTime: "SYS:standard",
+            },
+        },
+    }),
+});
+// ============================================
+// SAFE RESPONSE (Response Size Limiting)
+// ============================================
+const MAX_RESPONSE_SIZE = 200_000; // 200KB
+export function safeResponse(data, context) {
+    const jsonStr = JSON.stringify(data);
+    const sizeBytes = Buffer.byteLength(jsonStr, "utf-8");
+    if (sizeBytes > MAX_RESPONSE_SIZE) {
+        logger.warn({ sizeBytes, maxSize: MAX_RESPONSE_SIZE, context }, `Response exceeds size limit, truncating`);
+        if (Array.isArray(data)) {
+            const truncated = data.slice(0, Math.max(1, Math.floor(data.length * 0.5)));
+            return truncated;
+        }
+        if (typeof data === "object" && data !== null) {
+            const obj = data;
+            for (const key of ["items", "results", "data", "rows"]) {
+                if (Array.isArray(obj[key])) {
+                    obj[key] = obj[key].slice(0, Math.max(1, Math.floor(obj[key].length * 0.5)));
+                    return obj;
+                }
+            }
+        }
+    }
+    return data;
+}
+// ============================================
+// RETRY + CIRCUIT BREAKER + TIMEOUT
+// ============================================
+const backoff = new ExponentialBackoff({
+    initialDelay: 100,
+    maxDelay: 5_000,
+});
+const retryPolicy = retry(handleAll, {
+    maxAttempts: 3,
+    backoff,
+});
+const circuitBreakerPolicy = circuitBreaker(handleAll, {
+    halfOpenAfter: 60_000,
+    breaker: new ConsecutiveBreaker(5),
+});
+const timeoutPolicy = timeout(30_000, TimeoutStrategy.Cooperative);
+const policy = wrap(timeoutPolicy, circuitBreakerPolicy, retryPolicy);
+// ============================================
+// WRAPPED API CALL WITH LOGGING
+// ============================================
+export async function withResilience(fn, operationName) {
+    try {
+        logger.debug({ operation: operationName }, "Starting API call");
+        const result = await policy.execute(() => fn());
+        logger.debug({ operation: operationName }, "API call succeeded");
+        return result;
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        logger.error({ operation: operationName, error: error.message, stack: error.stack }, "API call failed after retries");
+        throw error;
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,2 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const tools: Tool[];

package/dist/tools.js

@@ -0,0 +1,260 @@
+export const tools = [
+    {
+        name: "reddit_ads_get_client_context",
+        description: "Get a quick overview of the Reddit Ads account. Returns account info and active campaign count.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                account_id: {
+                    type: "string",
+                    description: "Ad account ID. Uses default if not provided.",
+                },
+            },
+        },
+    },
+    {
+        name: "reddit_ads_get_accounts",
+        description: "List all Reddit ad accounts accessible to this user.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "reddit_ads_get_campaigns",
+        description: "List all campaigns for a Reddit ad account.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                account_id: {
+                    type: "string",
+                    description: "Ad account ID. Uses default if not provided.",
+                },
+            },
+        },
+    },
+    {
+        name: "reddit_ads_get_ad_groups",
+        description: "List ad groups for a Reddit ad account, optionally filtered by campaign.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                account_id: { type: "string", description: "Ad account ID. Uses default if not provided." },
+                campaign_id: { type: "string", description: "Optional - filter to a specific campaign." },
+            },
+        },
+    },
+    {
+        name: "reddit_ads_get_ads",
+        description: "List ads for a Reddit ad account, optionally filtered by ad group.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                account_id: { type: "string", description: "Ad account ID. Uses default if not provided." },
+                ad_group_id: { type: "string", description: "Optional - filter to a specific ad group." },
+            },
+        },
+    },
+    {
+        name: "reddit_ads_get_performance_report",
+        description: "Get a performance report for Reddit ads. Spend values are in microcurrency (divide by 1,000,000 for dollars).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                account_id: { type: "string", description: "Ad account ID. Uses default if not provided." },
+                start_date: { type: "string", description: "Start date YYYY-MM-DD. Defaults to 7 days ago." },
+                end_date: { type: "string", description: "End date YYYY-MM-DD. Defaults to today." },
+                fields: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Metric fields. Defaults to impressions, clicks, spend, ctr, cpc, ecpm. Available: impressions, reach, clicks, spend, ecpm, ctr, cpc, video_watched_25/50/75/100_percent, conversion_purchase_clicks, etc.",
+                },
+                breakdowns: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Breakdown dimensions: ad_id, campaign_id, ad_group_id, date, country, region, community, placement, device_os.",
+                },
+            },
+        },
+    },
+    {
+        name: "reddit_ads_get_daily_performance",
+        description: "Get daily performance breakdown for the last N days. Convenience tool with date breakdown.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                account_id: { type: "string", description: "Ad account ID. Uses default if not provided." },
+                days: { type: "number", description: "Number of days to look back. Defaults to 7." },
+            },
+        },
+    },
+    {
+        name: "reddit_ads_create_campaign",
+        description: "Create a new Reddit ad campaign. Created as PAUSED by default for safety.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Campaign name." },
+                objective: {
+                    type: "string",
+                    description: "Campaign objective: CONVERSIONS, TRAFFIC, AWARENESS, VIDEO_VIEWS, APP_INSTALLS, CONSIDERATION.",
+                },
+                daily_budget_dollars: { type: "number", description: "Daily budget in dollars (e.g. 50.00 for $50/day)." },
+                start_time: { type: "string", description: "Start datetime in ISO 8601 (e.g. 2026-03-17T00:00:00Z)." },
+                account_id: { type: "string", description: "Ad account ID. Uses default if not provided." },
+                end_time: { type: "string", description: "Optional end datetime in ISO 8601." },
+                configured_status: { type: "string", description: "ACTIVE or PAUSED. Defaults to PAUSED." },
+            },
+            required: ["name", "objective", "daily_budget_dollars", "start_time"],
+        },
+    },
+    {
+        name: "reddit_ads_update_campaign",
+        description: "Update an existing Reddit campaign. Only pass fields you want to change.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaign_id: { type: "string", description: "The campaign ID to update." },
+                account_id: { type: "string", description: "Ad account ID. Uses default if not provided." },
+                name: { type: "string", description: "New campaign name." },
+                daily_budget_dollars: { type: "number", description: "New daily budget in dollars." },
+                configured_status: { type: "string", description: "ACTIVE or PAUSED." },
+                end_time: { type: "string", description: "New end datetime in ISO 8601." },
+            },
+            required: ["campaign_id"],
+        },
+    },
+    {
+        name: "reddit_ads_create_ad_group",
+        description: "Create an ad group within a campaign. Created as PAUSED by default.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaign_id: { type: "string", description: "Parent campaign ID." },
+                name: { type: "string", description: "Ad group name." },
+                bid_dollars: { type: "number", description: "Bid amount in dollars (e.g. 5.00 for $5 CPM)." },
+                start_time: { type: "string", description: "Start datetime in ISO 8601." },
+                account_id: { type: "string", description: "Ad account ID. Uses default if not provided." },
+                end_time: { type: "string", description: "Optional end datetime." },
+                bid_strategy: { type: "string", description: "CPM, CPC, or CPV. Defaults to CPM." },
+                configured_status: { type: "string", description: "ACTIVE or PAUSED. Defaults to PAUSED." },
+                optimization_goal: { type: "string", description: "IMPRESSIONS, CLICKS, CONVERSIONS, etc." },
+                subreddit_names: { type: "array", items: { type: "string" }, description: "Subreddit names to target (without r/ prefix)." },
+                interest_ids: { type: "array", items: { type: "string" }, description: "Interest category IDs for targeting." },
+                geo_country_codes: { type: "array", items: { type: "string" }, description: 'Country codes (e.g. ["US", "CA"]).' },
+                device_types: { type: "array", items: { type: "string" }, description: "Device types: DESKTOP, MOBILE, TABLET." },
+            },
+            required: ["campaign_id", "name", "bid_dollars", "start_time"],
+        },
+    },
+    {
+        name: "reddit_ads_update_ad_group",
+        description: "Update an existing ad group. Only pass fields you want to change.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ad_group_id: { type: "string", description: "The ad group ID to update." },
+                account_id: { type: "string", description: "Ad account ID. Uses default if not provided." },
+                name: { type: "string", description: "New ad group name." },
+                bid_dollars: { type: "number", description: "New bid in dollars." },
+                configured_status: { type: "string", description: "ACTIVE or PAUSED." },
+                end_time: { type: "string", description: "New end datetime in ISO 8601." },
+            },
+            required: ["ad_group_id"],
+        },
+    },
+    {
+        name: "reddit_ads_create_ad",
+        description: "Create a new Reddit ad within an ad group. Created as PAUSED by default.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ad_group_id: { type: "string", description: "Parent ad group ID." },
+                name: { type: "string", description: "Internal ad name." },
+                headline: { type: "string", description: "Ad headline (max 300 chars)." },
+                click_url: { type: "string", description: "Landing page URL." },
+                account_id: { type: "string", description: "Ad account ID. Uses default if not provided." },
+                thumbnail_url: { type: "string", description: "URL to image asset (for image ads)." },
+                body_text: { type: "string", description: "Optional body text." },
+                call_to_action: { type: "string", description: "CTA: SIGN_UP, LEARN_MORE, SHOP_NOW, INSTALL, GET_QUOTE, CONTACT_US, DOWNLOAD." },
+                configured_status: { type: "string", description: "ACTIVE or PAUSED. Defaults to PAUSED." },
+                creative_type: { type: "string", description: "IMAGE, VIDEO, CAROUSEL, or TEXT. Defaults to IMAGE." },
+                video_url: { type: "string", description: "URL to video asset (for video ads)." },
+                post_url: { type: "string", description: "URL to existing Reddit post to promote." },
+            },
+            required: ["ad_group_id", "name", "headline", "click_url"],
+        },
+    },
+    {
+        name: "reddit_ads_update_ad",
+        description: "Update an existing ad. Only pass fields you want to change.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ad_id: { type: "string", description: "The ad ID to update." },
+                account_id: { type: "string", description: "Ad account ID. Uses default if not provided." },
+                name: { type: "string", description: "New ad name." },
+                headline: { type: "string", description: "New headline text." },
+                click_url: { type: "string", description: "New landing page URL." },
+                configured_status: { type: "string", description: "ACTIVE or PAUSED." },
+                call_to_action: { type: "string", description: "New CTA button text." },
+            },
+            required: ["ad_id"],
+        },
+    },
+    {
+        name: "reddit_ads_pause_items",
+        description: "Pause one or more campaigns, ad groups, or ads.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                item_type: { type: "string", description: "Type: CAMPAIGN, AD_GROUP, or AD." },
+                item_ids: { type: "array", items: { type: "string" }, description: "List of IDs to pause." },
+                account_id: { type: "string", description: "Ad account ID. Uses default if not provided." },
+            },
+            required: ["item_type", "item_ids"],
+        },
+    },
+    {
+        name: "reddit_ads_enable_items",
+        description: "Enable (unpause) one or more campaigns, ad groups, or ads.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                item_type: { type: "string", description: "Type: CAMPAIGN, AD_GROUP, or AD." },
+                item_ids: { type: "array", items: { type: "string" }, description: "List of IDs to enable." },
+                account_id: { type: "string", description: "Ad account ID. Uses default if not provided." },
+            },
+            required: ["item_type", "item_ids"],
+        },
+    },
+    {
+        name: "reddit_ads_search_subreddits",
+        description: "Search for subreddits to use as targeting in ad groups.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: 'Search query (e.g. "ecommerce", "fulfillment", "shopify").' },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "reddit_ads_get_interest_categories",
+        description: "Get available interest categories for ad group targeting.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "reddit_ads_search_geo_targets",
+        description: "Search geographic targeting options (countries, regions).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: 'Search query (e.g. "United States", "California").' },
+            },
+        },
+    },
+];

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "mcp-reddit-ads",
+  "version": "1.0.0",
+  "description": "MCP server for Reddit Ads API v3 with campaign, ad group, ad management, and performance reporting.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "config.example.json"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"fs=require('fs');cp=require('child_process');sha=cp.execSync('git rev-parse --short HEAD 2>/dev/null||echo unknown').toString().trim();fs.writeFileSync('dist/build-info.json',JSON.stringify({sha,builtAt:new Date().toISOString()}))\"",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run"
+  },
+  "author": "drak-marketing",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.5.0",
+    "cockatiel": "^3.2.1",
+    "pino": "^8.21.0",
+    "pino-pretty": "^13.1.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.18"
+  }
+}