reddit-ads

mcp-reddit-ads

Reddit Ads API v3 用の MCP サーバーです。Claude を介して、キャンペーン管理、広告作成、パフォーマンスレポート、オーディエンスターゲティングを行います。

特長

• 18 個のツールで、キャンペーン、広告グループ、広告に関する CRUD 全般をカバー
• 日別内訳を含むパフォーマンスレポート
• サブレディット、インタレスト、地域を対象としたターゲティング
• 一括での一時停止／有効化操作
• デフォルトでは安全に動作：新しいエンティティはすべて一時停止（PAUSED）状態で作成
• 予算入力はドル単位（Reddit のマイクロ通貨形式に自動変換）

インストール

npm install mcp-reddit-ads

または、リポジトリをクローンします。

git clone https://github.com/mharnett/mcp-reddit-ads.git
cd mcp-reddit-ads
npm install
npm run build

設定

セキュリティ： .mcp.json ファイルを共有したり、Git にコミットしたりしないでください。API 認証情報が含まれている可能性があります。.mcp.json を .gitignore に追加してください。

1. Reddit OAuth アプリ

reddit.com/prefs/apps で Reddit OAuth アプリを作成します。

• 「script」タイプを選択します
• クライアント ID とクライアントシークレットを控えます
• adsread adsedit read スコープを指定してリフレッシュトークンを取得します

2. 環境変数

環境変数で認証情報を設定します。

変数	説明
REDDIT_CLIENT_ID	OAuth アプリのクライアント ID
REDDIT_CLIENT_SECRET	OAuth アプリのクライアントシークレット
REDDIT_REFRESH_TOKEN	ads スコープを持つ OAuth リフレッシュトークン
REDDIT_ADS_MCP_WRITE	true に設定すると、変更を伴うツール（作成／更新／一時停止／有効化）が有効になります。未設定の場合は読み取り専用（デフォルト）です。

デフォルトでは読み取り専用

v1.1.0 以降、MCP は読み取り専用モードで起動します。読み取り／レポート／ターゲティング用の 10 個のツールは常に公開されますが、変更を伴う 8 個のツール（キャンペーン、広告グループ、広告の作成／更新、一括での一時停止／有効化）は、サーバーの環境で REDDIT_ADS_MCP_WRITE=true が設定されていない限り、ツール一覧に表示されず、呼び出し時にも拒否されます。これにより、何気ないチャットメッセージによって稼働中の広告費が誤って変更されるのを防ぎます。変更を実際に適用するセッションでは、意図的に書き込みを有効にしてください。

3. 設定ファイル

config.example.json を config.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
  }
}

環境変数は設定ファイルの値より優先されます。

使用方法

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： macOS では ~/Library/Application Support/Claude/claude_desktop_config.json に、Windows では %APPDATA%\Claude\claude_desktop_config.json に追加します。

ツール

コンテキスト

ツール	説明
reddit_ads_get_client_context	アカウント情報を取得し、API の接続を確認します
reddit_ads_get_accounts	認証済みユーザーがアクセスできるすべての広告アカウントを一覧表示します

読み取り

ツール	説明
reddit_ads_get_campaigns	任意のステータスフィルターを指定してキャンペーンを一覧表示します
reddit_ads_get_ad_groups	キャンペーンの広告グループを一覧表示します
reddit_ads_get_ads	広告グループの広告を一覧表示します
reddit_ads_get_performance_report	キャンペーン／広告グループ／広告の集計パフォーマンス指標を取得します
reddit_ads_get_daily_performance	日ごとのパフォーマンス内訳を取得します

書き込み：キャンペーン

ツール	説明
reddit_ads_create_campaign	新しいキャンペーンを作成します（デフォルトでは一時停止（PAUSED））
reddit_ads_update_campaign	キャンペーン名、予算、目標、またはステータスを更新します

書き込み：広告グループ

ツール	説明
reddit_ads_create_ad_group	ターゲティングを指定して新しい広告グループを作成します（デフォルトでは一時停止（PAUSED））
reddit_ads_update_ad_group	広告グループの入札額、ターゲティング、またはステータスを更新します

書き込み：広告

ツール	説明
reddit_ads_create_ad	見出し、本文、URL、メディアを指定して新しい広告を作成します（デフォルトでは一時停止（PAUSED））
reddit_ads_update_ad	広告クリエイティブまたはステータスを更新します

一括操作

ツール	説明
reddit_ads_pause_items	複数のキャンペーン、広告グループ、または広告を一度に一時停止します
reddit_ads_enable_items	複数のキャンペーン、広告グループ、または広告を一度に有効化します

ターゲティング

ツール	説明
reddit_ads_search_subreddits	ターゲティング用にキーワードでサブレディットを検索します
reddit_ads_get_interest_categories	ターゲティングで利用可能な興味カテゴリを一覧表示します
reddit_ads_search_geo_targets	地理的ターゲティングのオプション（国、地域、大都市圏）を検索します

主な規則

• 支出額は API からマイクロ通貨単位で返されます（1 ドル = 1,000,000 マイクロ通貨単位）。ドル単位の金額を得るには、1,000,000 で割ってください。予算の入力にはドルを指定でき、自動的に換算されます。
• 日付と時刻には ISO 8601 形式（YYYY-MM-DDTHH:MM:SSZ）を使用します。
• 新しいエンティティのステータスはデフォルトで PAUSED です。配信を開始するには、ステータスを明示的に ACTIVE に設定してください。
• レポート指標はデフォルトで config.json に設定されたものが使用されますが、リクエストごとに上書きできます。

アーキテクチャ

• レジリエンス：API 呼び出しのリトライポリシーとサーキットブレーカーに cockatiel を使用します
• ロギング：pino による構造化ロギング
• レスポンスの切り詰め：MCP メッセージの制限内に収めるため、大きな API レスポンスは 200KB で切り詰められます
• 認証：アクセストークンを自動更新する OAuth 2.0 リフレッシュトークンフロー

ライセンス

MIT -- LICENSE を参照してください。

作者

Mark Harnett / drak-marketing によって開発されました。