X Ads

この動画では、サンプルデータを使ったホスト版 getmcpads を紹介しています。クリエイティブギャラリーやアラートから、Google Sheets へのエクスポートや一括ローンチまで、MCP Apps はホスト版製品に含まれます。このリポジトリでは、単体で動作するネイティブ API ツールを提供します。

読み取りツール 25 個 · 書き込みツール 19 個（デフォルトでは無効）。

独自のプラットフォーム認証情報と、Claude Desktop、Claude Code、Cursor などの stdio MCP に対応したクライアントを使って、ローカルで実行できます。リクエストはプラットフォームに直接送信されます。対応する ChatGPT のセットアップを含む、管理された接続を利用する場合は、ホスト版をご利用ください。

新着情報

v1.0.1：初の単体リリース · 2026 年 9 月 20 日

• レビュー済みのネイティブツールのサブセットを使用して、初の実行可能な単体サーバーを作成しました。
• アカウント ID の明示的な指定を必須とし、デフォルトを読み取り専用に設定して、書き込みをプレビューし、ネイティブのページネーションを維持します。
• 固定された X エンドポイント、上限付きの応答、タイムアウト、認証情報の秘匿化を使用し、書き込みの自動再試行は行いません。
• Node.js 22.12 以降を必須とし、CI で Node 22/24 を確認します。
• 脆弱性のある依存関係を更新し、MCP カタログを再生成しました。

変更履歴全文 · ソース同期の詳細 · すべてのリリース

アップグレード時の注意

Node.js 22.12 以降が必要です。CI では Node 22 と 24 を対象にしています。保存済みの引数を再利用する前に、現在のツールスキーマを確認してください。書き込みは引き続きオプションであり、明示的な確認が必要です。ホスト版のクリエイティブ連携機能と MCP Apps UI は、このリリースには含まれません。

このリリースをインストールする

これは GitHub のソースリリースです。npm 版と MCP Registry 版は別途公開されています。以下のコマンドはこの特定のバージョンを選択します。このドキュメントの後半にある、バージョンを固定しない npx の例では、npm で現在利用できるバージョンが選択されます。

git clone --branch v1.0.1 --depth 1 https://github.com/get-mcp-ads/x-ads-mcp-server.git
cd x-ads-mcp-server
npm ci
npm run build

MCP クライアントを設定し、node を実行して、後述するプラットフォーム認証情報とともに dist/cli.js の絶対パスを指定してください。

管理された接続をご希望ですか？ ホスト版 getmcpads で X Ads を利用する。アカウントを接続し、アシスタントがアクセスできるデータを選択して、ホスト版 MCP 接続をご利用ください。現在の機能とプランについては、サイトをご覧ください。

設定

クライアントのシークレット設定で、以下の環境変数を指定してください。

変数	用途
X_ADS_ACCESS_TOKEN	ユーザーの OAuth 2.0 アクセストークンです。アプリ専用のベアラートークンでは不十分です。
X_ADS_ACCOUNT_IDS	必須のカンマ区切りアカウント ID です。トークンでアクセスできるアカウントに制限されます。
X_ADS_SCOPES	トークンに実際に付与されたスコープです。デフォルトは ads.read です。
X_ADS_ENABLE_WRITES	デフォルトは false です。書き込み機能が有効になるのは、値が正確に true の場合のみです。

トークンの取得と Ads Project へのアクセスには、X の公式セットアップガイドを利用してください。 レポートには ads.read、キャンペーンの変更には ads.write、アップロードとメディアライブラリへの書き込みには media.write を使用してください。 X_ADS_SCOPES を設定しても、権限は付与されません。このパッケージはトークンを受け取りますが、OAuth のブラウザーフローを実行したり、ローテーションするリフレッシュトークンを保存したりすることはありません。トークンの有効期限が切れたら、安全に更新してサーバーを再起動してください。

安全性と対応範囲

書き込みはデフォルトでプレビューされます。confirm: true を指定して再度呼び出す前に、対象のアカウント、対象項目、パラメーターを正確に確認してください。 キャンペーンと広告グループは一時停止状態で作成されます。有効化すると広告予算が消費される可能性があります。メディアのアップロードでは X API クレジットが消費される可能性があり、サイズは 4 MB までに制限されています。 結果が不明な場合、書き込みを自動で再試行しないでください。まずアカウントを読み取り、状態を照合してください。 選択したアカウントのチェックは、ディスパッチ前に適用され、アカウント検出の応答をフィルタリングします。不明な引数は拒否されます。 ネイティブのページネーション、アトリビューション、金額を表す _micro フィールドは保持されます。マイクロ単位は、アカウント通貨の 100 万分の 1 です。

このサーバーが公開するのは、公式 API のうちレビュー済みの一部です。上流に新しいツールが追加されても、自動的に公開されることはありません。 ネイティブのメディア読み取りと書き込みが含まれます。ホスト型クリエイティブギャラリー、ビジュアルエディター、MCP Apps の UI は対象外です。 正確なスキーマは tools/list または server-card.json で、プロバイダーの詳細は公式 API リファレンスで確認してください。

ホスト型オプション

X Ads 向け getmcpadsでは、ホスト型接続とアカウント選択を管理できます。 ホスト型リリースとソースリリースでは内容が異なる場合があります。お問い合わせ先：[email protected]。

開発

npm run typecheck
npm run lint
npm run build
npm test
npm run catalog

すべてのテストは合成レスポンスを使用してオフラインで実行されます。実際のアカウントは変更されません。

ツール

すべてのツールを以下に示します。パラメーターと出力のスキーマ全体については、server-card.jsonを参照してください。

25 個の読み取りツール

| ツール | 目的 | | --- | --- | | `x_ads_list_ads_accounts` | 認証済みユーザーがアクセスできる広告アカウントを一覧表示します | | `x_ads_list_campaigns` | アカウントのキャンペーンを一覧表示します | | `x_ads_get_campaign` | ID を指定して単一のキャンペーンを取得します | | `x_ads_list_funding_instruments` | 広告アカウントの支払い手段を一覧表示します | | `x_ads_list_line_items` | 広告アカウントの広告グループを一覧表示します | | `x_ads_get_line_item` | ID を指定して単一の広告グループを取得します | | `x_ads_list_promoted_posts` | 広告アカウントのプロモーション対象の投稿（プロモツイート）を一覧表示します | | `x_ads_list_targeting_criteria` | 広告アカウントの広告グループのターゲティング条件を一覧表示します | | `x_ads_list_account_posts` | 広告アカウントでプロモーションに使用できる投稿（ツイート）を一覧表示します | | `x_ads_list_web_event_tags` | 広告アカウントのウェブサイトコンバージョンイベントタグ（ピクセル）を一覧表示します。タグの ID は、コンバージョン広告グループの `primary_web_event_tag` として指定する値です | | `x_ads_list_line_item_placements` | 広告グループの商品タイプごとに有効な配置の組み合わせを一覧表示します | | `x_ads_get_account_stats` | 広告アカウントの同期分析データ（インプレッション、エンゲージメント、費用）を取得します | | `x_ads_get_active_entities` | 指定期間内に指標が変化した広告エンティティを一覧表示します（アカウント統計をリクエストする前に使用してください） | | `x_ads_get_campaign_reach` | キャンペーンのリーチと平均フリークエンシーの指標を取得します | | `x_ads_search_targeting_interests` | ターゲティング可能な興味カテゴリを名前で検索します。 | | `x_ads_search_targeting_locations` | ターゲティング可能な地域を名前で検索します。 | | `x_ads_list_cards` | 広告アカウントのカードを一覧表示します | | `x_ads_get_card` | ID を指定して単一のカードを取得します | | `x_ads_list_media_library` | 広告アカウントのメディアライブラリオブジェクトを一覧表示します | | `x_ads_get_media_library_item` | メディアキーを指定して単一のメディアライブラリオブジェクトを取得します | | `x_ads_get_promoted_post` | ID を指定して単一のプロモーション対象の投稿を取得します | | `x_ads_get_targeting_criterion` | ID を指定して単一のターゲティング条件を取得します | | `x_ads_list_post_previews` | 公開済みまたは予約済みの投稿のレンダリング済み HTML プレビューを取得します | | `x_ads_get_web_event_tag` | ID を指定して単一のウェブサイトコンバージョンイベントタグを取得します | | `x_ads_get_media_upload_status` | 接続済みの X ユーザーが所有するアップロードの処理状況を確認します。 |

19 個の書き込みツール

デフォルトでは無効です。明示的に確認されない限り、呼び出しはプレビューを返します。使用前に設定と正確なスキーマを確認してください。

ツール	目的
x_ads_create_campaign	広告アカウントにキャンペーンを作成します。
x_ads_update_campaign	キャンペーン名を変更するか、一時停止します（entity_status=PAUSED）。
x_ads_activate_campaign	キャンペーンを有効化します（entity_status=ACTIVE に設定）。
x_ads_create_line_item	キャンペーンの下にラインアイテム（広告グループ）を作成します。
x_ads_update_line_item	ラインアイテムの入札額、予算、名前、スケジュール、掲載場所、目標、ペーシング、オーディエンス拡張（Optimized Targeting を有効にするには audience_expansion=EXPANDED に設定）、または entity_status を更新します。
x_ads_activate_line_item	ラインアイテムを有効化します（entity_status=ACTIVE に設定）。
x_ads_promote_post	投稿をラインアイテムに紐付け、広告クリエイティブとして設定します。
x_ads_add_targeting_criterion	ラインアイテムにターゲティング条件を1つ追加します（条件ごとに1回呼び出します）。
x_ads_remove_targeting	ラインアイテムからターゲティング条件を削除します（ターゲティングの誤りを元に戻します）。
x_ads_create_ad_post	広告クリエイティブとして使用する、プロモーション専用の投稿（「nullcasted」）を作成します。
x_ads_create_card	JSON コンポーネントのペイロードからカードを作成します。
x_ads_delete_card	広告アカウントからカードを削除します。
x_ads_create_media_library_item	既存のメディアキーを、アカウントのメディアライブラリに名前付きアイテムとして登録します。
x_ads_delete_media_library_item	広告アカウントからメディアライブラリオブジェクトを削除します（デフォルトはプレビュー）。
x_ads_update_media_library_item	メディアライブラリオブジェクトのメタデータ（名前、タイトル、説明など）を更新します（デフォルトはプレビュー）。
x_ads_create_web_event_tag	ウェブサイトのコンバージョンイベントタグ（ピクセル）を作成します。返された ID は、ラインアイテムの primary_web_event_tag に設定できます（デフォルトはプレビュー）。
x_ads_delete_web_event_tag	ウェブサイトのコンバージョンイベントタグを削除します（デフォルトはプレビュー）。
x_ads_update_web_event_tag	ウェブサイトのコンバージョンイベントタグを更新します（デフォルトはプレビュー）。
x_ads_upload_media	画像、GIF、または MP4 クリップを X にアップロードします。

ライセンス

Apache License 2.0。NOTICE を参照してください。

getmcpads のその他のサービス

Meta Ads · Google Ads · Google Analytics 4 · Google Search Console · TikTok Ads · Pinterest Ads

getmcpads の Emmanuel がメンテナンスしています。お問い合わせ：[email protected]。