Reddit Ads

Reddit Ads 用 MCP サーバー（mcp-server-reddit-ads）

実際に Reddit 広告を運用している広告主が構築し、実運用で検証した、書き込み操作と段階的な安全制御に対応する Reddit Ads API v3 MCP サーバーです。MCP クライアントに、キャンペーン、広告グループ、広告、パフォーマンスレポートへの読み取りアクセスを提供するほか、一時停止、作成、予算や入札額の変更、ターゲティングの編集、広告グループ間での広告のコピーを行う、制限付きの書き込みツールも提供します。

要件

• Reddit Ads アカウントと、アプリを登録するためのビジネス管理者アクセス権。
• Node.js 20 以降。
• MCP クライアント（Claude Code、Claude Desktop、その他）。

はじめに

ご利用の環境に合った方法を選んでください。Claude Code または Claude Desktop ではプロンプトを一度貼り付ける方法、その他のクライアントでは手動で設定する方法があります。どの方法でも、インストール時は読み取り専用で、最後の手順で書き込みを意図的に有効にするまではアカウントに変更を加えられません。

Claude Code で簡単に設定する（推奨）

Claude Code をお使いの場合は、定型作業を任せられます。以下のプロンプト全体をコピーして Claude Code に貼り付けてください。

Set up the mcp-server-reddit-ads MCP server for me so I can manage my Reddit Ads
account from here. Install it read-only for now - no write access. Please:

1. Read the setup instructions at https://github.com/camlowe/mcp-server-reddit-ads
2. Check I'm on Node.js 20 or newer.
3. Walk me through registering a Reddit app, since only I can do that part. Tell me
   exactly where to click and which two values (client ID and client secret) to copy.
4. Run `npx mcp-server-reddit-ads auth` and guide me through the browser login.
5. Add the server to my .mcp.json using the credentials from the auth step, with the
   write tier set to read-only.
6. Confirm the server loads and list my Reddit ad accounts to prove it works.

Do not enable any write access yet. I'll ask for that later when I'm ready.

Claude はこの README を読み、ユーザー自身でしか行えない手順を具体的に案内し、npx mcp-server-reddit-ads auth を実行して .mcp.json を作成し、サーバーが読み込まれることを確認します。後で変更を加えるときは、書き込みティアを上げるよう依頼するだけです。

Claude Desktop で簡単に設定する

Claude Desktop はターミナルコマンドを代わりに実行できないため、このプロンプトでは、ユーザーがコマンドを1つ実行し、設定ファイルを1つ編集する間、丁寧に案内します。新しい Claude Desktop チャットに貼り付けてください。

I want to set up the mcp-server-reddit-ads MCP server so I can manage my Reddit Ads
account with you. I'm not a developer, so please guide me one step at a time with
simple, copy-pasteable instructions, and wait for me to confirm each step before
moving to the next.

Look up the setup details at https://github.com/camlowe/mcp-server-reddit-ads. The
main steps are: register a Reddit app to get a client ID and secret, run a one-time
`npx mcp-server-reddit-ads auth` command in my terminal to log in, and add the server
to my Claude Desktop config file. Set it up read-only so nothing in my account can
change until I decide to turn writes on.

いずれの方法でも、Reddit アプリの登録（以下の手順1）とブラウザーでのログイン承認はご自身で行う必要があります。これらは自動化できません。

高度な設定（手動）

その他の MCP クライアントをお使いの場合や、手動で設定したい場合の手順です。所要時間は約5分です。

1. Reddit アプリを登録する

1. ads.reddit.com の Reddit Ads ダッシュボードを開き、ビジネス管理者アクセス権のあるアカウントでサインインします。
2. 右上の Business settings（歯車／設定メニュー）を開き、次に Developer Applications、続いて Create App を選択します。
3. アプリ名を入力し、redirect URI を正確に http://localhost:8080 に設定して、連絡先担当者（ビジネス管理者）を選択します。保存してください。

Reddit に、手順2で必要な2つの値が表示されます。

• Client ID - 短い文字列（およそ22文字。例：Ab3xK9zQ1rStUvWxYzAbCd）で、アプリ名のすぐ下に表示されます。Reddit では「client ID」というラベルなしで表示されることが多いため、見落としやすい値です。アプリ名そのものではなく、アプリのタイトルの下にあるコードです。
• Client secret - secret と明記されたフィールドに表示される、より長い値です。すぐにコピーしてください。なくした場合は、同じページから新しいシークレットを再生成できます。

reddit.com/prefs/apps は使わないでください。Responsible Builder Policy により、新しいアプリは通知なく拒否されます。そのため、広告主が利用できる方法は Ads 開発者ポータルだけです。

2. リフレッシュトークンを発行する

組み込みのセットアップヘルパーを実行します。

npx mcp-server-reddit-ads auth

手順1のクライアント ID とシークレットを尋ねられます（または、設定済みの場合は REDDIT_CLIENT_ID と REDDIT_CLIENT_SECRET から読み込みます）。ブラウザーで Reddit の認証ページを開き、承認されるまで http://localhost:8080 で待機します。

承認すると、設定の保存方法を選べます。

Where should I save this? (I'll patch the file, keeping anything already there.)
  [1] Claude Code    ./.mcp.json
  [2] Claude Desktop <your platform's claude_desktop_config.json>
  [3] Just print it  (don't write any file)

[1] または [2] を選ぶと、認証情報がディスクに直接書き込まれます（既存ファイルは <file>.bak にバックアップされ、他のサーバーはそのまま保持されます）。そのため、機密情報を MCP クライアントに渡す必要はありません。自分で設定したい場合は [3] を選ぶと、そのまま貼り付けられるブロックが表示されます。TTY を検出できない場合（出力がパイプ経由の場合など）は、メニューを省略してブロックを表示します。

失敗した場合は、よくある原因であるポート8080がすでに使用されている場合と、リダイレクト URI の不一致（アプリのリダイレクト URI は正確に http://localhost:8080 である必要があります）の対処方法が表示されます。

3. MCP クライアントにサーバーを追加する

手順 2 で [1] または [2] を選んだ場合、追加はすでに完了しています。手順 4 に進んでください。それ以外の場合は、表示されたブロックをクライアントの設定に貼り付けます。auth コマンドによって 3 つの認証情報の値が入力された状態で、次の形式になっています。

{
  "mcpServers": {
    "reddit-ads": {
      "command": "npx",
      "args": ["-y", "mcp-server-reddit-ads"],
      "env": {
        "REDDIT_CLIENT_ID": "your-client-id",
        "REDDIT_CLIENT_SECRET": "your-client-secret",
        "REDDIT_REFRESH_TOKEN": "your-refresh-token",
        "REDDIT_ADS_WRITE_TIER": "read"
      }
    }
  }
}

Claude Code のユーザーは、代わりにコマンドラインから登録できます。

claude mcp add reddit-ads \
  -e REDDIT_CLIENT_ID=your-client-id \
  -e REDDIT_CLIENT_SECRET=your-client-secret \
  -e REDDIT_REFRESH_TOKEN=your-refresh-token \
  -e REDDIT_ADS_WRITE_TIER=read \
  -- npx -y mcp-server-reddit-ads

4. 再起動して確認する

サーバーを読み込ませるためにクライアントを再起動します（Claude Code では、プロンプトが表示されたらサーバーを承認し、/mcp で読み込まれたことを確認します）。次に、自分の Reddit 広告アカウントを一覧表示してと依頼します。アカウント ID（a2_...）が表示されるはずです。管理しているアカウントが 1 つだけの場合は、設定の REDDIT_ADS_ACCOUNT_ID にその ID を設定して再起動すると、以後のリクエストでアカウント名を指定する必要がなくなります。

5. 読み取り専用のクエリを試す

接続できました。読み取り専用で利用できます。最初の質問として、次のようなものを試してください。

• 「Reddit 広告アカウントの概要を教えてください。」
• 「直近 7 日間のキャンペーン別のパフォーマンスを表示してください。」
• 「現在有効な広告グループを教えてください。」

ほとんどのユーザーは、日常的にはこの状態で利用します。変更を加える場合は、書き込みを有効にしてください。

6. 必要に応じて書き込みを有効にする

新規インストールでは、一時停止、作成、編集はできません。変更を許可するには、設定の REDDIT_ADS_WRITE_TIER を引き上げて再起動します。まずは safe から始めてください（このレベルでは、支出を開始または増加させる操作はできません）。配信を再開したり、予算、入札単価、ターゲティングを変更したりする場合にのみ、spend に引き上げます。各レベルで許可される操作の詳細については、書き込みレベルを参照してください。

書き込みレベル

書き込みはデフォルトで無効です。REDDIT_ADS_WRITE_TIER では 2 段階で有効化するため、読み取りまたは safe レベルで誤操作しても支出は開始されません。

設定したレベルを超えるツールは、拒否されるだけでなく、クライアントのツール一覧から完全に非表示になります。読み取り専用のセッションでは 18 個のツールが公開されます。モデルはツールの存在を知らないため、update_budget を実行することすらできません。非表示のツールが何らかの方法で呼び出された場合、サーバーは、そのツールの使用が許可されるレベルを示すエラーを返して拒否します。

レベル	許可される操作	ルール
read（デフォルト）	書き込みはできません。	読み取りのみです。
safe	一時停止、作成（一時停止状態で作成）、名前変更、広告のコピー。	配信の開始や拡大はできません。
spend	safe のすべてに加え、有効化、予算、入札単価、ターゲティングの変更。	配信の開始、再開、または変更が可能です。

環境変数

変数	意味
REDDIT_CLIENT_ID、REDDIT_CLIENT_SECRET、REDDIT_REFRESH_TOKEN	必須です。いずれかが設定されていない場合、auth コマンドを案内するメッセージとともに起動に失敗します。
REDDIT_ADS_WRITE_TIER	read（デフォルト）、safe、または spend。
REDDIT_ADS_ACCOUNT_ID	任意のデフォルトアカウント（a2_...）です。アカウントが 1 つだけのユーザーは、account_id を指定する必要がなくなります。

ツール

グループ	ツール	ティア
診断	get_server_status	read
アカウント	get_accounts、get_account_overview	read
エンティティ	get_campaigns、get_campaign、get_ad_groups、get_ad_group、get_ads、get_ad	read
クリエイティブ	get_ad_creative	read
検索	find_entity	read
レポート	get_performance_report、get_daily_performance、compare_periods、compare_ads	read
ターゲティングデータ	search_subreddits、get_interest_categories、search_geo_targets	read
作成	create_campaign、create_ad_group、create_ad	safe
一時停止／名前変更	pause_items、update_name	safe
コメント	update_ad_comments	safe
ワークフロー	copy_ads	safe
再開	enable_items	spend
金額	update_budget、update_bid	spend
配信設定	update_targeting	spend
広告 URL	update_ad_url	spend

注意：

• get_campaigns、get_ad_groups、get_ads は任意の status フィルター（ACTIVE、PAUSED、ARCHIVED）を受け取り、クライアント側で configured_status に適用します。
• ツールの結果は 200,000 文字に制限されています。結果が切り詰められた場合はその旨が示され、クエリを絞り込むよう提案されます。
• get_performance_report は、小文字でわかりやすい指標名（impressions、clicks、spend、cpc、conversion_page_visit_clicks など）を受け取ります。呼び出し前にローカルで検証され、入力ミスがあった場合は最も近い候補が提案されます。
• create_ad_group には conversion_pixel_id が必要です。また、キャンペーン予算最適化が有効な場合は create_campaign にも必要です（2026-07-13 以降、Reddit により必須となっています）。ピクセル ID は Reddit Ads ダッシュボードの Events Manager にあり、観測されたデータでは広告アカウント ID と同じです。
• copy_ads は広告を別の広告グループに複製します（Reddit は複製ごとにプロモート投稿の複製を作成します）。utm_campaign やその他のクリック URL のクエリパラメーターを書き換えるオプションもあります。
• Reddit API では広告コピー（見出し、本文）は変更できません。編集可能な投稿プロパティは allow_comments のみです。広告の内容を変更するには、新しいコピーで広告を作成して有効にし、古い広告を一時停止してください。

Reddit API の注意点

クライアントには、ライブ API で検証済みの動作が実装されています。特に混乱を招きやすいものを以下に示します。

• 更新には PATCH を使い、PUT は使いません。誤った HTTP メソッドに対して、Reddit は 405 ではなく 404 を返します。 メソッドのバグは、リソースが存在しない場合とまったく同じように見えます。これは上流パッケージのすべての書き込みを失敗させるバグです。
• 単一リソースにはベースパス（/ads/{id}）を使用し、コレクションと作成にはアカウントスコープのパス（/ad_accounts/{id}/ads）を使用します。 使い分けを誤ると 404 が返されます。
• 金額はすべてマイクロ通貨（通貨単位の 100 万分の 1）です。 このサーバーは読み取り時に USD に変換し、書き込み時に元の単位に戻すため、ツールの入力と出力はドル単位です。
• レポート指標名はリクエストでは大文字の列挙値ですが、レスポンスでは小文字で、表記にも一貫性がありません（CONVERSION_SIGN_UP_CLICKS と CONVERSION_SIGNUP_TOTAL_VALUE など）。わかりやすい小文字の名前を使用してください。サーバーが検証してマッピングします。
• 書き込み後は effective_status ではなく configured_status を参照してください。 設定値はすぐに更新されますが、有効ステータスの反映には数分かかることがあります。
• 広告コピーは編集できません。 クリエイティブはプロモート投稿に紐付いており、PATCH /posts/{id} で更新できるフィールドは allow_comments の 1 つだけです。見出しと本文は明確に拒否されます。コピーを変更するには、新しい広告（create_ad、作成時は一時停止状態）を配信し、古い広告を一時停止します。これによりメッセージごとにパフォーマンス履歴も維持されるため、いずれにしても適切なワークフローです。

開発

npm install
npm test          # unit and contract tests (no live API calls)
npm run typecheck
npm run lint
npm run build
npm run smoke     # manual, hits the live API; needs real credentials in env

免責事項

このソフトウェアは、LICENSEに定めるとおり、いかなる種類の保証もなく、「現状有姿」かつ「提供可能な範囲」で提供されます。バグやエラーが含まれる場合があり、提供される安全対策や制御機能が機能しなかったり、予期しない動作をしたりする可能性があります。ご自身の責任でご利用ください。

このツールは、稼働中の Reddit 広告エンティティの作成、名前の変更、一時停止、再開、再設定を行えるほか、予算、入札単価、ターゲティングを変更できます。これらの操作により、実際の広告費が発生、増加、またはその他の影響を受ける可能性があります。以下については、お客様が単独で責任を負うものとします。

• このサーバーの使用によって発生する料金、広告費、または金銭的な結果。
• アカウントに対して行われるすべての変更を、ご自身で確認し、検証すること。
• Reddit API の認証情報を安全に保管すること。
• Reddit Ads API を Reddit の利用規約に従って使用すること。

作者は、広告費の損失または意図しない支出、キャンペーンの設定ミスまたは一時停止、意図しない変更、その他このソフトウェアの使用に起因するいかなる損害についても責任を負いません。安全制御機能が操作を防げなかった場合も含まれます。

このプロジェクトは、独立した非公式のクライアントです。Reddit, Inc. との提携、同社による推奨、または同社からの後援を受けていません。

ライセンス

MIT