mcp-microsoft-ads

非公式 — Microsoft とは提携・承認・サポート関係にありません。 これは Microsoft Advertising 向けのサードパーティ製 MCP (Model Context Protocol) サーバーです。「MCP」は、AI アシスタント (Claude やその他の MCP クライアント) が実際のシステム — ここではあなたの Microsoft Ads アカウント — に対してツールを呼び出せるようにするオープンプロトコルです。

安全性を最優先する Microsoft Ads MCP: キャンペーン、広告グループ、キーワード、否定キーワード、地域ターゲティング、広告スケジュール、拡張機能、メディア、オーディエンス、コンバージョン目標の管理に加え、パフォーマンスレポートと Ad Insight キーワード調査をカバーする 47 のツールを備えています。AI アシスタントにライブ広告アカウントへの書き込みアクセスを与えても、白紙の小切手を与えることにならないように設計されています。

「安全性最優先」の理由

すべての変更ツールはデフォルトでオフです。書き込みを有効にするのは 1 つの環境変数だけで、それでもすべての書き込みは、Microsoft の API に 1 回の呼び出しが届く前に、同じ多層ゲートを通過します:

1. MS_ADS_ENABLE_WRITES=true — これがないと、すべての書き込みツールは実行を拒否します。初期状態では読み取り専用サーバーです。

2. ドラフト → 確認。 書き込みツールは単独の呼び出しでは決して変更を行いません。プレビュー (draft_id と変更される内容の正確な詳細) を返し、あなた — または MCP クライアント — が confirm_and_apply(draft_id) を呼び出すまで、何も適用されません。

3. 支出上限。 ドラフト作成と適用の両方で、MS_ADS_MAX_DAILY_BUDGET (デフォルト 1000) または MS_ADS_MAX_CPC (デフォルト 50) を超える金額を拒否します。USD ではなく、アカウントの通貨でです。

4. スマート入札のフェイルクローズドガード。 入札/調整の書き込みは、手動入札戦略 (ManualCpc, EnhancedCpc, ManualCpv, ManualCpm, ManualCpa) に許可リスト化されています。認識されない戦略や自動化された戦略 (MaxConversions, TargetCpa, TargetRoas, …) は安全と見なされず拒否されます。

5. JSONL 監査ログ。 すべてのドラフトとすべての適用は、ローカルの追記専用 JSONL ファイルに追記されます — このサーバーが実際に行ったことのプレーンテキストの記録です。

380 以上のオフラインテスト (ライブ API 呼び出しなし) で、レール、SOAP 配管の癖、ドラフト/確認ライフサイクルをフェイクに対して検証しています。

「ドラフト → 確認」がそうではないものについて正直に

ドラフト → 確認は、単一呼び出しの事故に対するプレビューゲートです — 入札のタイプミス、コピーペーストの間違い、間違ったツールの呼び出しなどです。これは人間の承認によるアクセス制御ではありません: ドラフトを作成した同じ MCP クライアントが、その直後に confirm_and_apply を呼び出すことができ、サーバーは人間の介入を要求しません。すべての書き込みを人間がレビューしたい場合は、それは独自のワークフロー (別の承認ステップ、人間専用クライアントなど) で強制する必要があります — このサーバーはそれを代行しません。

1 つの書き込みは、上記の多層ストーリーでは完全に制限できないため、別途取り上げられています: apply_recommendation は Microsoft が決定した変更に委ねます — プレビューできるのはレコメンデーション ID だけで、変更自体はプレビューできないため、実際の金銭的影響はこのサーバーの支出上限で事前にチェックできません。これは (Microsoft のレコメンデーションが役立つことがあるため) 保持され、例外であることが大声でラベル付けされ、MS_ADS_ENABLE_WRITES と独自のフラグ MS_ADS_ALLOW_APPLY_RECOMMENDATION の両方の背後にゲートされています — そのため、一般的に書き込みを有効にしても、これは有効になりません。

このサーバーがしないこと

• 品質スコアの診断はありません。

• 一時的な API 障害に対する自動再試行/バックオフはありません (失敗した呼び出しは失敗します。再試行はあなた次第です)。

• Microsoft の SOAP Bing Ads SDK に基づいていますが、Microsoft はサポート終了を発表しています — 以下を参照。

Related MCP server: OpenAI Ads MCP

SOAP のサポート終了と REST ロードマップ

このサーバーは bingads SOAP SDK に基づいています。Microsoft は SOAP が 2027-01-31 にサポート終了となることを発表し、2026-10-01 より前に移行することを推奨しています (それ以降の新しい API 機能は REST のみで提供されます)。Microsoft の Migrate to REST API ガイドと Python SDK SOAP-to-REST migration guide を参照してください。このサーバーのツールを REST に移植することがロードマップ項目です — SOAP は今日でも動作し、EOL 日まで廃止されることはありませんが、長期的に計画しないでください。

比較

比較は 2026-08-24 に最終確認しました。このプロジェクトは、読み取り専用かどうか以外の他の行の正確な現在の機能セットを知っているとは主張しません — 詳細は各プロジェクトのリポジトリ/ドキュメントを確認してください。上記の差別化要因 (オプトイン書き込み、2 段階のドラフト→確認、支出上限、スマート入札のフェイルクローズドガード、JSONL 監査ログ、380 以上のオフラインテスト) がこのプロジェクトの基盤です。

インストール

git clone https://github.com/wvuhskr/mcp-microsoft-ads.git
cd mcp-microsoft-ads
python3 -m venv .venv  # requires Python >= 3.12
.venv/bin/pip install -e ".[dev]"

完全なセットアップ — Azure アプリ登録、開発者トークン、最初の OAuth サインイン — は docs/setup.md にあります。このセクションでは、資格情報がすでに存在する場合のサーバーの実行のみを説明します。

資格情報

資格情報はリポジトリの外、YAML ファイル (デフォルト ~/.mcp-microsoft-ads/credentials.yaml、MS_ADS_CREDENTIALS_PATH で上書き) にあります: developer_token, client_id, client_secret, refresh_token, customer_id, account_id, tenant。

6 つの静的フィールド (refresh_token 以外) は、代わりに MS_ADS_DEVELOPER_TOKEN, MS_ADS_CLIENT_ID, MS_ADS_CLIENT_SECRET, MS_ADS_CUSTOMER_ID, MS_ADS_ACCOUNT_ID, MS_ADS_TENANT 環境変数として設定できます — 両方存在する場合は環境変数がファイルより優先されます。refresh_token はファイルのみです: Microsoft は使用のたびにそれをローテーションし、ローテーションされたトークンは次の実行のためにどこかに永続化する必要がありますが、環境変数ではそれができません。サーバーは各ローテーションを資格情報ファイルに原子的に永続化します (.bak が保持されます)。

初回実行のウォークスルー

1. ブートストラップサインイン:

.venv/bin/python -m mcp_microsoft_ads.reauth

ブラウザで対話型 OAuth サインインを実行し、結果の refresh_token を資格情報ファイルに書き込みます。このステップが依存する Azure アプリ登録と開発者トークンについては docs/setup.md を参照してください。 2. サーバーを読み取り専用で起動します (MS_ADS_ENABLE_WRITES はまだ設定しないでください)。MCP クライアントから health_check を呼び出し、次に list_accounts や get_account_info を呼び出します。 3. アカウントが意図したものであることを確認します — それらの呼び出しで返されたアカウント ID、アカウント名、アカウント通貨を、このサーバーに触れさせようとしているアカウントと照合します。以下の支出上限はそのアカウントの通貨で強制されるため、通貨の不一致は書き込みを有効にする前に検出する価値があります。 4. その後にのみ MS_ADS_ENABLE_WRITES=true を設定し (必要に応じて MS_ADS_ALLOW_APPLY_RECOMMENDATION=true も)、サーバーを再起動します。

MCP クライアント設定

両方の設定は、上記の venv が ~/mcp-microsoft-ads/.venv にあることを前提としています — それをマシン上の実際の絶対パスに置き換えてください (両方のクライアントは ~ ではなく絶対パスを必要とします)。

Claude Code (プロジェクト内の .mcp.json、または claude mcp add 経由):

{
  "mcpServers": {
    "microsoft-ads": {
      "command": "/home/you/mcp-microsoft-ads/.venv/bin/python",
      "args": ["-m", "mcp_microsoft_ads.server"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "microsoft-ads": {
      "command": "/home/you/mcp-microsoft-ads/.venv/bin/python",
      "args": ["-m", "mcp_microsoft_ads.server"]
    }
  }
}

2 つの同時クライアントを同じ資格情報ファイルに向けないでください

同時クライアント間での 1 つの資格情報ファイルの共有はサポートされていません。 refresh_token はローテーションされる共有の可変ファイルです: リフレッシュのたびに新しいトークンが生成され、古いトークンは即座に無効になります。また、ローテーションを永続化する読み取り-変更-書き込みは、このレイヤーで 2 つの別々のプロセス間で安全に直列化できません。同じファイルからリフレッシュを競合する 2 つのクライアントは、無効化されたトークンで互いに行き詰まらせる可能性があります。複数の同時クライアント (例: Claude Code と Claude Desktop を同時に開く) が必要な場合は、各クライアントに独自の資格情報ファイルと独自の Azure アプリ登録を与えてください — MS_ADS_CREDENTIALS_PATH をクライアントごとに異なる値に設定し、それぞれを独自の reauth 実行でブートストラップします。

環境変数

通貨に関する注意: MS_ADS_MAX_DAILY_BUDGET と MS_ADS_MAX_CPC は、USDとの換算ではなく、アカウントの通貨単位の金額と直接比較されます。1000 という上限は、アカウントの通貨単位が何であれ、その1000単位を意味します。

テスト / lint

.venv/bin/python -m pytest -q     # offline test suite, ~370 tests, no live API calls
.venv/bin/python -m ruff check .  # lint

ドキュメント

• docs/setup.md — Azureアプリ登録、開発者トークン、完全なブートストラップ。

• SECURITY.md — 脆弱性の報告方法。

• CHANGELOG.md — リリース履歴。

ライセンスとサポート

MITライセンス — LICENSE を参照。これはベストエフォート型の無償オープンソースプロジェクトです。SLAはなく、応答時間も保証されません。Issueはベストエフォートで監視・トリアージされます。