amazon_ads_mcp

ローカル

github.com/KuudoAIビジネス・マーケティング742 週間前に更新

amazon_ads_mcp について

Amazon Ads API MCP サーバーは、Model Context Protocol に基づくオープンソースの実装で、Amazon Advertising API の多くの操作を MCP ツールとして提供します。広告開発者、代理店、マーケティングチームが AI を使った広告運用を構築する際に向いています。エラー応答には、エージェントが次のリクエストを修正するための案内が含まれます。

主な機能

01アカウント、レポート、SP、SB、SD、DSP などの API を網羅
02NA、EU、FE のリージョンエンドポイントへの自動ルーティング
03設定により選択可能な Ads API v1 パッケージ
04ポートを設定可能な Docker Compose によるデプロイ
05エージェント向けの修正案内を含むエラー応答

活用シーン

01Claude Desktop からの広告キャンペーンの照会と管理
02カスタム広告レポートの生成と運用パフォーマンスの分析
03マーケティング用チャットボットや広告自動化サービスの構築

MCP 対応

本プロジェクトは MCP サーバーであり、Amazon Advertising API の操作を MCP クライアントや AI モデルが呼び出せるツールとして公開します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "tspicer-amazon-ads": {
      "command": "uvx",
      "args": [
        "amazon-ads-mcp"
      ],
      "env": {
        "AMAZON_ADS_AUTH_METHOD": "<AMAZON_ADS_AUTH_METHOD>",
        "AMAZON_AD_API_CLIENT_ID": "<AMAZON_AD_API_CLIENT_ID>",
        "AMAZON_AD_API_CLIENT_SECRET": "<AMAZON_AD_API_CLIENT_SECRET>",
        "AMAZON_AD_API_REFRESH_TOKEN": "<AMAZON_AD_API_REFRESH_TOKEN>",
        "AMAZON_AD_API_PROFILE_ID": "<AMAZON_AD_API_PROFILE_ID>",
        "OPENBRIDGE_REFRESH_TOKEN": "<OPENBRIDGE_REFRESH_TOKEN>",
        "OPENBRIDGE_API_KEY": "<OPENBRIDGE_API_KEY>",
        "OPENBRIDGE_REMOTE_IDENTITY_ID": "<OPENBRIDGE_REMOTE_IDENTITY_ID>",
        "AMAZON_ADS_REGION": "<AMAZON_ADS_REGION>",
        "AMAZON_AD_API_PACKAGES": "<AMAZON_AD_API_PACKAGES>",
        "AMAZON_ADS_DOWNLOAD_AUTH_TOKEN": "<AMAZON_ADS_DOWNLOAD_AUTH_TOKEN>"
      }
    }
  }
}

起動コマンドuvx amazon-ads-mcp

設定が必要な環境変数

AMAZON_ADS_AUTH_METHODシークレットAuthentication method: direct or openbridge.

AMAZON_AD_API_CLIENT_IDAmazon Ads API client ID for direct auth.

AMAZON_AD_API_CLIENT_SECRETシークレットAmazon Ads API client secret for direct auth.

AMAZON_AD_API_REFRESH_TOKENシークレットAmazon Ads API refresh token for direct auth.

AMAZON_AD_API_PROFILE_IDAmazon Ads profile ID for direct auth.

OPENBRIDGE_REFRESH_TOKENシークレットOpenbridge refresh token (API key).

OPENBRIDGE_API_KEYシークレットOpenbridge API key (alias for OPENBRIDGE_REFRESH_TOKEN).

OPENBRIDGE_REMOTE_IDENTITY_IDOpenbridge remote identity ID.

AMAZON_ADS_REGIONAmazon Ads API region (na/eu/fe).

AMAZON_AD_API_PACKAGESComma-separated API packages to load.

AMAZON_ADS_DOWNLOAD_AUTH_TOKENシークレットOptional bearer token to protect download routes.

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

pypiamazon-ads-mcp0.2.4stdio

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

Amazon Ads API MCP SDK

Amazon Advertising API 向けの Model Context Protocol（MCP）SDK で、AI を活用した広告アプリケーションを構築できます

Openbridge が ❤️ と ☕ を込めて作成

MCP レジストリ ID（安定したパッケージ名を表示するクライアントやカタログ向け）：io.github.KuudoAI/amazon_ads_mcp

Kuudo における位置づけ
MCP ツールとは？
Amazon Ads API MCP SDK とは？
クイックスタート
インストール
設定（認証、パッケージ、プロファイル、リージョン）
レポートとエクスポートのダウンロード
MCP クライアントの例（Claude Desktop）
コンテキストの制限
コードモード
ツールの監査
バックグラウンドタスク
よくある質問
トラブルシューティング
ドキュメント一覧

Kuudo における位置づけ

このリポジトリは、より広範な Amazon エージェントプラットフォームのツールレイヤーです。Kuudo は Amazon エージェントにツール、ナレッジ、ワークフロー、そして作業場所を提供します。このリポジトリが担うのはツールです。

レイヤー	提供するもの	場所
MCP サーバー	エージェントが呼び出すツールです。ここでは Amazon Ads のほか、Selling Partner と Vendor Central を扱います	このリポジトリ、および MCP ツールリファレンス
スキル	より高水準のワークフローです。再利用可能でバージョン管理された複数ステップの Amazon 向け手順で、これらのツールを組み合わせ、実行が開始される前に人間の確認を待ちます	Amazon Agent Skills
Agent Atlas	ナレッジです。Ads、Seller Central、Vendor Central にまたがる Amazon の運用ナレッジをインデックス化し、出典を引用して回答します	Amazon Agent Atlas
Agent Flow	作業場所です。Amazon のデータを独自のクラウドに取り込み、エージェントが推測ではなく実際の数値に基づいて回答します	Amazon Agent Flow

このリポジトリはプラットフォーム全体ではなく、その一つのレイヤーとして捉えてください。以下の操作はエージェントが呼び出せるものであり、Skills はエージェントが実行するものです。

MCP ツールとは？

MCP（Model Context Protocol）は、AI モデルと Amazon Ads のような外部システムをつなぐ翻訳者のようなものです。各 MCP ツールは、Amazon Ads とのやり取り方法を AI に伝えるリモコンのボタンのようなものです。MCP ツールがなければ、AI は Amazon Ads とどのように「会話」すればよいのか分かりません。

MCP ツールを使うと：

AI は呼び出すべき正確なエンドポイントを把握できます。
AI はキャンペーンレポート、予算、ターゲティングデータを安全にリクエストできます。
すべてが構造化されているため、AI が当てずっぽうで操作して問題を起こすことはありません。

👉 要するに、MCP ツールとは、AI が Amazon Ads API を安全に利用するための、分かりやすく整理されたツールキットです。

🚀 Amazon Ads API MCP SDK とは？

Amazon Ads API MCP SDK は、AI を活用した広告ツール、チャットボット、自動化サービスの作成に向けた堅牢な基盤を提供する、オープンソースの実装です。

✨ 主な機能

🔌 MCP 統合：AI アプリケーションとの統合に対応した、Model Context Protocol への完全準拠
🌍 複数リージョンのサポート：NA、EU、FE のリージョンエンドポイントに対応し、自動ルーティングを実行
📊 包括的な API カバレッジ：キャンペーン、プロフィール、レポート、DSP、AMC ワークフローなどに対応
📝 型安全性：包括的な型ヒントを備えた、Pydantic モデルの完全サポート
🧪 本番環境対応：テスト、検証、エラー処理を含む

🎯 ユースケース

Claude Desktop との統合

キャンペーン管理：Claude にキャンペーンの作成、更新、分析を依頼できます
パフォーマンス分析：広告パフォーマンスを AI で分析できます
予算の最適化：パフォーマンスに基づいた予算の調整を Claude に提案してもらえます
クリエイティブのテスト：広告クリエイティブの改善に関する推奨事項を得られます
レポート作成：必要に応じて、カスタムレポートや分析情報を生成できます

AI アプリケーション

マーケティングチャットボット：Amazon Ads のキャンペーンを管理できる会話型 AI を構築できます
レポートの自動化：AI を活用した分析情報とパフォーマンス分析を提供します
スマートな予算管理：AI を使って予算をインテリジェントに最適化します
クリエイティブの最適化：AI を活用して広告クリエイティブをテストし、最適化します

エンタープライズサービス

マーケティング自動化プラットフォーム：Amazon Ads を既存のマーケティングツールに統合します
代理店管理システム：複数のクライアント、アカウントにまたがる広告管理を実現します
E コマース統合：Amazon Ads を E コマースプラットフォームに接続します
分析ダッシュボード：広告パフォーマンスをリアルタイムでモニタリングします

開発者ツール

API ラッパー：特定のユースケースに合わせたカスタム SDK を作成できます
テストフレームワーク：Amazon Ads 統合の自動テストを実施できます
開発ツール：ローカル開発やデバッグに役立つユーティリティを提供します

この Ads MCP の特徴

他の Amazon Ads MCP は、成功する一般的なケースには対応できます。しかし、エージェントが妥当な操作ミスをした途端に機能しなくなります。Amazon Ads API では、他のほとんどの大規模な API と比べても、妥当な操作ミスが非常に多く発生するためです。v1 のレポートカタログでは v3 とは異なる用語が使われています。ドキュメントは、移行の世代ごとに分散しています。また、エージェントや人間がどのチュートリアルで学習したかによって、同じフィールドにもっともらしい名前が 3 つ存在することもあります。

こんな経験はありませんか

これらをひとつの問題として捉えたことがなくても、次のような症状には覚えがあるでしょう。

作業が進み始めたところで「会話を圧縮中…」と表示される
タスクの途中で「使用量の上限に達しました」と表示され、トークンを使ったのに成果がない
「コンテキストウィンドウの上限を超えました」と表示され、最初からやり直してすべてを説明し直す
3 ターン前にエージェントが見つけた解決策を、いつの間にか忘れている
ツール呼び出しが 5 回、そのうち 4 回はリトライで、進展はなし
同じエラーをチャットに 3 回も貼り付け直す

それはモデルが愚かなのではありません。API の仕様がコンテキストを消費しているのです。曖昧なエラーが試行錯誤を引き起こし、試行錯誤がウィンドウを埋め、ウィンドウがいっぱいになると役に立つ情報が次々と押し出されます。エージェントでは、フィールド名、本文の形式、フィルター演算子、日付の配置、広告主アカウントの形式を間違えることで、4～12 回もの往復が発生することがあります。

ここでは、間違った操作が正しい操作につながります

このサーバーは、異なる前提に基づいて構築されています。エラーが発生する場所こそが、ドキュメントが役立つ場所です。 あらゆる失敗は学びの機会です。同じエージェントでも次のエージェントでも、再トレーニングやプロンプトの更新、記憶の小細工をしなくても、前回より賢く次の試行ができるようサーバーを設計しています。

サーバーは何が問題だったのか、そしてなぜ間違えたのかを伝えます
すべての失敗が修正アクションに変わります。モデルはヒントを読み、先に進むだけです
5 回のツール呼び出しが必要だったデバッグの流れが、修正後は 2 回の呼び出しに短縮されます
1 週間後に同じ間違いをしても、バリデーター、エイリアステーブル、非推奨の形式を記したテーブルがそのまま使えるため、コンテキストを再び消費することはありません
忘れてしまうような、コンテキスト外の暗黙知はありません

失敗するたびに、そのコストは下がっていきます。すべてのエージェントが、同じ信頼できる情報源から学びます。再試行には進むべき方向があります。この積み重ねこそ、実用的なスマートエージェントソリューションの姿です。

あらゆるケースがエッジケースです。ぜひご協力ください

すべてのエッジケースを見つけられるわけではありません。Amazon の API は非常に広範で、移行の経緯は複雑です。また、現実世界の障害は誰も予想できないほど多様です。私たちが約束するのは、エラーから学べるようにすること、エージェントが実際に触れる場所にドキュメントを置くこと、間違った操作のたびに次の操作を簡単にすることを方針とすることです。

エンベロープが役に立たなかった場合、つまりヒントが曖昧だった、提案が間違っていた、あるいはヒントがまったくなかった場合は、ぜひフィードバックをお寄せください。イシューを作成し、エンベロープを貼り付けて、期待していた内容をお知らせください。 この方針は、対応できるケースの範囲によってその価値が決まります。

クイックスタート

前提条件： Docker（推奨）、ソースから実行する場合は Python 3.10 以降、Amazon Ads API へのアクセス（独自の開発者アプリ、または Openbridge などのパートナー経由）。

git clone https://github.com/KuudoAI/amazon-ads-mcp.git && cd amazon-ads-mcp
cp .env.example .env を実行し、認証情報を追加します（設定を参照）。
docker compose up -d
MCP クライアントを http://localhost:<PORT>/mcp/ に接続します。.env.example では PORT=9080 が設定されています（必要に応じて .env で変更してください）。

OAuth の手順、クライアントの JSON サンプル、変数の完全なリファレンスについては、以下の設定、INSTALL.md、AGENTS.mdをご覧ください。

📚 Amazon Ads MCP には何が含まれていますか？

MCP サーバーは、Amazon Ads API の幅広い範囲を反映しています。有効にした各パッケージは、一連の API 操作に対応します。キャンペーン管理（Amazon Ads API v1）、エクスポート、Amazon Marketing Cloudなどが含まれます。

MCP で利用できる Amazon API サービスの代表的な一覧は次のとおりです。

アカウント
オーディエンス
レポート
ブランド指標
スポンサープロダクト
スポンサーブランド
スポンサーディスプレイ
Amazon DSP
Amazon Attribution
レコメンデーションとインサイト
クリエイティブ
変更履歴
データプロバイダー
プロダクト
統合事前モデレーション
モデレーション
Amazon Marketing Stream
ロケーション
エクスポート
メディアプランニング
Amazon Ads API v1

🧪 Amazon Ads API v1

Amazon Ads API v1 は、Amazon Ads API に対する新たなアプローチとして、共通モデルを通じてすべての Amazon 広告製品でシームレスなエクスペリエンスを提供するために、一から構築されました。この共通モデルの大きな利点の一つは、クライアントライブラリー生成ツールなどのコード生成ツールとの互換性が向上することです。

⚠️ ベータに関するお知らせ：これらの API は現在 Amazon でベータ版です。機能やエンドポイントは変更される場合があります。本番環境での使用にはご注意ください。

パッケージ名	説明	プレフィックス
`ads-api-v1-all`	Ads API v1 の統合 ALL サーフェス	`allv1_`
`ads-api-v1-sp`	Sponsored Products v1	`spv1_`
`ads-api-v1-sb`	Sponsored Brands v1	`sbv1_`
`ads-api-v1-dsp`	Amazon DSP v1	`dspv1_`
`ads-api-v1-sd`	Sponsored Display v1	`sdv1_`
`ads-api-v1-st`	Sponsored Television v1	`stv1_`
`ads-api-v1-beta`	Ads API v1 の統合 BETA サーフェス	`beta_`

Ads API v1 パッケージを有効にするには、AMAZON_AD_API_PACKAGES 環境変数に追加します。

# Example: Enable the merged Ads API v1 ALL surface
AMAZON_AD_API_PACKAGES="profiles,ads-api-v1-all"

詳しくは、Amazon のキャンペーン管理の概要をご覧ください。

MCP サーバーにとどまらない機能

上記はすべてツールレイヤー、つまりエージェントが呼び出せる Amazon Ads の操作です。Kuudo はその周囲に 3 つのレイヤーを追加しており、操作の数だけを数える比較では、それらを見落としてしまいます。

機能	MCP サーバー単体	Kuudo
Amazon Ads API の操作を公開する	はい	はい
より高レベルな複数ステップのワークフロー	いいえ	はい、Skills として提供
再利用可能でバージョン管理されたワークフロー	いいえ	はい。各 Skill にバージョンが付与されます
公開前の人による承認	いいえ	はい。有効化には承認が必要です
ワークフローをフォークしてアカウントに合わせて変更する	いいえ	はい。Skills はプレーンなオープン形式です
インデックス化された Amazon の知識を、引用付きで回答	いいえ	はい、Agent Atlas を通じて提供
独自のアカウントデータを独自のクラウドに取り込む	いいえ	はい、Agent Flow を通じて提供
複数の MCP サーバーにまたがるワークフロー	いいえ	はい。Ads と Selling Partner および Vendor Central を連携
任意の MCP クライアントから実行する	場合による	はい。Claude、ChatGPT、Cursor などに対応

Kuudo は Skills を通じて、MCP ツールレイヤーの上に、より高レベルなワークフローを提供します。 Skill はこれらの操作を再現可能な Amazon の手順にまとめ、Atlas を使って根拠を補い、変更を適用する前に人の承認を待ちます。

インストール

Amazon Ads API MCP の実行には、🐳 Docker の使用をおすすめします。このリポジトリからイメージをビルドしてください（ここではサードパーティーレジストリーのイメージに対する docker pull はサポートしていません。リポジトリ内の Dockerfile と docker-compose.yaml を使用してください）。

pip、ソースチェックアウト、カスタム virtualenv、Docker を使わないデプロイ、Code Mode の追加処理など、個別のインストール方法については、インストールガイドをご覧ください。README では Docker の簡易手順を簡潔にまとめており、INSTALL.md にはインストール方法の全一覧と検証手順を記載しています。

git clone https://github.com/KuudoAI/amazon-ads-mcp.git
cd amazon-ads-mcp

環境変数のテンプレートをコピーします。

cp .env.example .env

.env を編集して設定を行います（デフォルトを変更する場合は PORT も設定してください）。

Docker Compose でサーバーを起動します（docker-compose.yaml に従って amazon-ads-mcp:latest をビルドし、タグ付けします）。

docker compose up -d

サーバーは、.env の PORT から割り当てられたホストポートでリッスンします（.env.example では 9080 を使用します）。

ログを確認します。

docker compose logs -f

サーバーを停止します。

docker compose down

検証、アップグレード、開発環境のセットアップ、Docker を使わないインストール方法については、インストールガイドをご覧ください。

設定

オペレーター／セルフホストする方： 以下の手順と .env ファイルに従ってください。チャットユーザー： サーバー接続後は、主にプロンプトを使って操作します。プロファイルとリージョンの動作については、広告主のプロファイルとリージョンをご確認ください。

Amazon Ads では、API へのすべての呼び出しを認証する必要があります。これが何を意味するかわからない場合は、Amazon のドキュメントをお読みください。

Amazon Ads API のオンボーディング概要：https://advertising.amazon.com/API/docs/en-us/guides/onboarding/overview
Amazon Ads API を使い始める：https://advertising.amazon.com/API/docs/en-us/guides/get-started/overview

API に接続する方法は 3 つあります。

独自のアプリを持ち込む（BYOA）
OpenBridge 管理の認証を使用する
Kuudo 管理の認証を使用する

独自の Amazon Ads API アプリを持ち込む

独自の Amazon Ads API アプリをお持ちの場合、または作成する場合は、以下の手順に従ってください。

1. Amazon にアプリケーションを登録する

Amazon Developer Console にアクセスします
Login with Amazon アプリケーションを作成するか、選択します
Client ID と Client Secret を控えます
コールバック URL を「Allowed Return URLs」に設定します。この URL は、この MCP サーバーの HTTP リスナーのホストとポートに一致する必要があります（.env の PORT を参照してください。.env.example では 9080 を使用します）。
- 本番環境の場合：https://your-server.com/auth/callback
- ローカル開発の場合：http://localhost:<PORT>/auth/callback（例：http://localhost:9080/auth/callback）

アプリが保護され、Amazon に承認されると、クライアント ID とシークレットが必要になります。

# Amazon Ads API Credentials (required)
AMAZON_AD_API_CLIENT_ID="your-client-id"
AMAZON_AD_API_CLIENT_SECRET="your-client-secret"

これらが .env ファイルに設定されていることを確認してください。また、同じ .env で認証方式を direct に設定してください。

AUTH_METHOD=direct

OAuth フローを完了する

Amazon への接続を認証するには、エンドユーザーとして OAuth ワークフローを完了する必要があります。まず、リージョンを設定します。認証はリージョン単位で行われるため、リージョンを設定しないと失敗する場合があります。サーバーのデフォルトリージョンは na です。ツール set_active_region を使ってリージョンを手動で設定できます。

ツール：set_active_region
パラメーター：na | eu | fe

プロンプトの例："現在のリージョンを eu に設定して"

ステップ 1：OAuth を開始する

Amazon Ads API に接続するには、MCP ツールを使用して OAuth フローを開始します。

ツール：start_oauth_flow
プロンプトの例："OAuth フローを開始して"

ステップ 2：Amazon Ads にリダイレクトする

この例では、ブラウザーウィンドウを開き、Amazon で承認を求めるリンクをクリックするよう促されます。

ステップ 3：リクエストを承認する

ブラウザーウィンドウで、Amazon から接続リクエストを承認するよう求められます。

ステップ 4：成功

問題がなければ、成功メッセージが表示されます。ブラウザーウィンドウを閉じて、クライアントに戻ることができます。別のメッセージが表示された場合は、手順をもう一度試し、設定項目がすべて正しいことを確認してください。

ステップ 5：確認

MCP サーバーが Amazon Ads API に接続されていることを確認するには、OAuth のステータスを確認します。

ツール：check_oauth_status
プロンプトの例："OAuth のステータスを確認して"

これで、Amazon Ads API システムの操作を開始できます。

パートナーアプリケーション：トークン認証

有効なアクセストークンを指定することで、Claude などのクライアントに認証を使用するよう設定できます。この方法は、サービスアカウント、長期間有効な API キー、CI/CD、認証を別途管理するアプリケーション、その他の非対話型認証方式に最適です。

Openbridge Partner App

Ads API パートナーアプリケーションプロバイダーとして、Openbridge は Amazon Ads API へのすぐに利用できるゲートウェイを提供します。Openbridge アカウントにログインし、トークンを発行したら、そのトークンをクライアント設定に設定します（下記を参照）。

まず、認証方法として Openbridge を設定します。

AUTH_METHOD=openbridge

サーバー設定はこれで完了です。サーバーにアクセスするには、Claude Desktop などのクライアントがトークンを直接渡すように設定する必要があります。（MCP クライアントの例：Claude Desktop を接続するを参照）

認証済み Amazon アカウント

Amazon の認証情報は Openbridge に保存されています。クライアントで最初に行うことは、現在の ID をリクエストすることです。"List my remote identities"。次に、これらの ID のいずれかを使用するよう MCP サーバーに指示します。"Set my remote identity to <>"。その後、該当アカウントにリンクされた List all of my Amazon Ad profiles を MCP に依頼できます。広告主が表示されない場合は、別の ID を設定してください。

Kuudo Partner App

Kuudo は、組織が管理する Amazon 接続から、有効期間の短い Amazon Ads 認証情報を発行できます。Kuudo M2M API キーを使用してサーバーを設定します。

AUTH_METHOD=kuudo
KUUDO_API_BASE_URL=https://amazon-spapi-dev.kuudo.ai/
KUUDO_API_KEY=sk_xxxxxx
KUUDO_PROVIDER=amazon_ads

API キーには amazon-connections:read と amazon-tokens:vend のスコープが必要です。起動時に既定の接続を選択するには KUUDO_REMOTE_IDENTITY_ID を設定するか、Amazon Ads 操作を呼び出す前に ID ツールを使用して接続を一覧表示し、選択してください。

パブリック HTTP デプロイでは、MCP 呼び出し元向けに MCP_INBOUND_TOKEN または信頼されたプロキシの HMAC 認証も設定する必要があります。

Amazon Ads MCP パッケージを設定する

特定のパッケージを有効にするには、カンマ区切りのパッケージリストを設定します。Ads API v1 を統合的にカバーする、簡潔な既定の設定は次のとおりです。

AMAZON_AD_API_PACKAGES="profiles,accounts-ads-accounts,reporting-version-3,amc-workflow,ads-api-v1-all"

サーバーで利用できるツールパッケージの一覧は次のとおりです。

profiles
test-account
forecasts
brand-stores-management
campaign-manage
accounts-manager-accounts
accounts-ads-accounts
accounts-portfolios
accounts-billing
accounts-account-budgets
audiences-discovery
reporting-version-3
brand-benchmarks
brand-metrics
stores-analytics
sponsored-products
sp-suggested-keywords
sponsored-brands-v4
sponsored-brands-v3
sponsored-display
dsp-measurement
dsp-advertisers
dsp-audiences
dsp-conversions
dsp-target-kpi-recommendations
amazon-attribution
audience-insights
partner-opportunities
tactical-recommendations
persona-builder
creative-assets
change-history
data-provider-data
products-metadata
products-eligibility
unified-pre-moderation-results
moderation-results
amazon-marketing-stream
locations
exports-snapshots
marketing-mix-modeling
reach-forecasting
amc-administration
amc-workflow
amc-rule-audience
amc-ad-audience
ads-api-v1-sp (ベータ)
ads-api-v1-sb (ベータ)
ads-api-v1-dsp (ベータ)
ads-api-v1-sd (ベータ)
ads-api-v1-st (ベータ)
ads-api-v1-all
ads-api-v1-beta (ベータ)

一部のパッケージが、より小さなグループに分かれていることにお気づきでしょう。たとえば Amazon Marketing Cloud には、amc-ad-audience、amc-administration、amc-rule-audience、amc-workflow のバンドルがあります。これは、多くの AI クライアントでコンテキスト制限を抑える効率化と最適化を実現するためです。

Amazon Ads MCP ツールについて

Amazon Ads MCP ツールのプレフィックス（キャンペーン管理を表す cm_ や Amazon Marketing Cloud を表す amc_ など）は、Ads API の各操作を整理するために使われます。

プレフィックスの例：

cm_ → キャンペーン／広告 API
amc_ → AMC 関連 API
dsp_ → DSP API
sd_ → Sponsored Display
ams_ → Amazon Marketing Stream
spv1_ → Sponsored Products v1 (Beta)
sbv1_ → Sponsored Brands v1 (Beta)
dspv1_ → Amazon DSP v1 (Beta)
sdv1_ → Sponsored Display v1 (Beta)
stv1_ → Sponsored Television v1 (Beta)

これにより、利用可能な API 操作に対応したツールのコレクションが作成されます。

キャンペーン管理（cm_）

cm_QueryCampaign — キャンペーンを検索
cm_CreateCampaign — キャンペーンを作成
cm_UpdateCampaign — キャンペーンを更新
cm_DeleteCampaign — キャンペーンを削除
cm_QueryAdGroup — 広告グループを検索

Sponsored Products（sp_）

sp_listProductAds — 商品広告を一覧表示
sp_createKeywords — キーワードを作成
sp_updateBids — キーワードの入札額を更新
sp_getNegativeKeywords — ネガティブキーワードを取得

AMC ワークフロー（amc_）

amc_listWorkflows — AMC ワークフローを一覧表示
amc_executeWorkflow — ワークフローを実行
amc_getWorkflowStatus — ワークフローのステータスを確認

ユーザーには次のようなツールが表示されます。

「Amazon Ads のキャンペーンを一覧表示して」
→ Claude が使用：cm_QueryCampaign
「AMC ワークフローを作成して」
→ Claude が使用するツールの例：amc_executeWorkflow（検出後に使用。正確な名前は有効になっているパッケージによって異なります）
「Sponsored Products 広告データをエクスポートして」 → Claude が使用：export_createAdExport

📥 レポートとエクスポートのダウンロード

ツールが Amazon からレポートまたはエクスポートを取得すると、MCP サーバーを実行しているマシンにファイルをダウンロードします（サーバーホスト上のローカルディスク、つまり Docker ボリューム、VM、またはベアメタルです。サーバーがそこで実行されていない限り、ノート PC ではありません）。デフォルトのベースディレクトリは ./data です（AMAZON_ADS_DOWNLOAD_DIR で変更できます）。ファイルは data/profiles/{profile_id}/… の下に整理されます。

MCP ツールはサーバー側のファイルを一覧表示して URL を作成し、クライアントが HTTP（GET /downloads、GET /downloads/{relative-path}）経由でデータを取得します。この処理では、最初にサーバーのストレージに保存せず、Amazon から MCP クライアントへ直接ストリーミングすることはありません。

ダウンロードには HTTP トランスポートを使用してください。--transport http を指定して実行するか、Docker をポート 9080 で実行します。stdio モードでは /downloads は登録されず、HTTP を使用しない場合、get_download_url ツールはエラーを返します。

レポートとエクスポートの違い

V3 非同期レポート： OpenAPI ツール createAsyncReport（POST）で作成し、getAsyncReport（GET）でステータスをポーリングしてから、download_export で完成したファイルをプロファイルストレージのサーバー上に保存します。
エクスポート（広告エクスポートなど）： OpenAPI ツール（例：export_CampaignExport）でジョブを作成し、export_GetExport でポーリングしてから、完了 URL を指定して download_export を呼び出します。これにより、ファイルがAmazon から取得され、サーバー上に書き込まれます（レポートと同じストレージ構成です）。

ワークフロー

アクティブなプロファイルを設定する（set_active_profile）ことで、ストレージと HTTP アクセスの対象を限定します。
ジョブを作成する： 適切な OpenAPI ツールを使用して、レポートまたはエクスポートを作成します。
完了するまでポーリングする： 対応する GET ツールを使用して、ステータスが COMPLETED になるまで確認します。
ダウンロードする： 完了レスポンスに含まれるダウンロード URL を指定して、download_export を呼び出します。
検出またはリンクを取得する： MCP ツールの list_downloads と get_download_url を使用します。
バイトデータを取得する： 手順 5 の URL に対して HTTP GET を実行します（ブラウザー、curl など）。

プロファイルフォルダー内のサブパスは、レポート／エクスポートの種類によって異なります（例：reports/…、exports/…）。URL は http://localhost:9080/downloads/{relative-path} のようになります。ここで、{relative-path} は list_downloads と一致します（例：reports/async/some-report.json.gz）。

直接 HTTP（curl）： /downloads は、実行中のサーバーでアクティブなプロファイル（そのプロセスで MCP 経由で設定したプロファイル）を使用します。No active profile と表示される場合は、まず同じサーバーに対して MCP 経由で set_active_profile を呼び出してください。認証マネージャーが設定されていない場合は、数値の ?profile_id= クエリパラメーターが受け入れられることがあります。デプロイ設定を確認してください。

プロンプトの例

タスク	プロンプトの例
レポートをダウンロードする	"2026年1月のスポンサープロダクトレポートを生成して"
利用可能なファイルを一覧表示する	"ダウンロードしたファイルを表示して"
ダウンロードリンクを取得する	"今作成したレポートのダウンロード URL を取得して"
種類で絞り込む	"ダウンロードしたキャンペーンエクスポートを一覧表示して"

HTTP ダウンロード API

# List available downloads (paths and URLs are profile-scoped)
curl http://localhost:9080/downloads

# Optional filter
curl 'http://localhost:9080/downloads?type=reports'

# Download one file (example path — use paths from list_downloads)
curl -O 'http://localhost:9080/downloads/reports/async/example-report.json.gz'

# If AMAZON_ADS_DOWNLOAD_AUTH_TOKEN is set
curl -H "Authorization: Bearer your-token" -O 'http://localhost:9080/downloads/exports/campaigns/example-export.json'

プロファイルの分離

ファイルは data/profiles/{profile_id}/ の下に保存されます。
ダウンロードツールと /downloads からは、アクティブなプロファイルのファイルのみ参照できます。
先にプロファイルを設定します："アクティブなプロファイルを 123456789 に設定して"。
プロファイルスコープモードでは、profiles/ の外にあるレガシーファイルは一覧表示されません。アクセスするには、data/profiles/{profile_id}/ の下に移動してください。

広告主プロファイルとリージョン

広告主プロフィールを設定する

Amazon によると、「プロフィールは、各呼び出しの管理範囲を決定することで、Amazon Ads API において重要な役割を果たします。特定のマーケットプレイスにおける広告主のデータやサービスにアクセスするには、プロフィール ID が必須の認証情報です。」

認証によってどのプロフィールにアクセスできるのか、わからない場合があります。認証でアクセス可能なすべての広告プロフィールを一覧表示できます。

ツール：ac_listProfiles
プロンプトの例：「広告主のプロフィール ID を一覧表示して」

警告： 大規模なアカウントでは、クライアントのコンテキスト制限を超えるほど大量のプロフィールが返されることがあります。検索時には、次のような範囲を指定できるツールを優先してください。

ツール：summarize_profiles — 「広告主プロフィールを要約して」
ツール：search_profiles — 「US で名前に Acme が含まれるプロフィールを探して」
ツール：page_profiles — 「UK の最初の 20 件のプロフィールを表示して」
ツール：refresh_profiles_cache — 「プロフィールリストのキャッシュを更新して」

応答には、次のプロフィール情報が含まれます。

profileId、countryCode、currencyCode
dailyBudget、timezone
accountInfo（type：seller/vendor/agency）

ここでは、リストにプロフィール ID 1043817530956285 が含まれていたとします。プロフィールの詳細を取得して、使用したいものかどうか、さらに詳しく確認できます。

ツール：ac_getProfile
プロンプトの例：「プロフィール ID 1043817530956285 の詳細を取得して」

これを使用したいプロフィールとする場合、API 呼び出しに必要な Amazon のプロフィールを設定する必要があります。

ツール：set_active_profile
プロンプトの例：「アクティブプロフィール ID を 1043817530956285 に設定して」

プロフィールを設定すると、次の内容が決まります。

アクセスするアカウントのデータ
レポートの通貨とタイムゾーン
利用可能なキャンペーン、広告、キーワード

プロフィール ID は、セッション中、バックグラウンドで設定されます。別のプロフィールに切り替える場合は、この手順を繰り返してください。

Amazon Ads API のほとんどの呼び出しでは、リージョンが必要です。各広告主プロフィール IDは、特定のリージョン／マーケットプレイスにある広告アカウントに関連付けられています。

リージョンは広告主プロフィールの一部です。set_active_profile で広告主プロフィールを設定すると、そのプロフィールに関連付けられたリージョンが自動的に設定されます。

ツール：set_active_profile

プロンプトの例：「アクティブな広告主プロフィールを 111111111111 に設定して」

プロフィール ID 111111111111 は na にあるため、プロフィールのリージョンに基づいてリージョンが設定されます。

アクティブリージョンを設定する

Amazon Ads MCP サーバーには、API リージョンをデフォルトとして設定したり、動的に管理したりするためのツールが含まれています。サーバーを再起動せずに、北米（na）、ヨーロッパ（eu）、極東（fe）の各リージョンを切り替えられます。

リージョンコード	名前	API エンドポイント
`na`	北米	https://advertising-api.amazon.com
`eu`	ヨーロッパ	https://advertising-api-eu.amazon.com
`fe`	極東	https://advertising-api-fe.amazon.com

リージョンを設定すると、システムは次の処理を自動的に行います。

API エンドポイントを更新する - API 呼び出しを正しいリージョンのエンドポイントにルーティングします
OAuth エンドポイントを更新する - そのリージョンに適したトークン更新エンドポイントを使用します
キャッシュされたトークンを消去する - 新しいリージョンで新たに認証できるようにします
その他の設定を保持する - プロフィール ID と ID 設定をそのまま維持します

重要：リージョンの不一致を避けてください： 広告主プロフィールに関連付けられていないリージョンを設定しようとすると、Ads API はリクエストを拒否します。たとえば、プロフィール ID が na に関連付けられている状態で、手動でリージョンを eu に設定すると、不一致が発生し、API リクエストが失敗します。

アクティブリージョンを取得する

設定されているリージョンがわからない場合は、リージョンを確認できます。

ツール：get_active_region
戻り値：現在のリージョン、エンドポイント、設定元

プロンプトの例：「現在のアクティブリージョンは？」

MCP クライアントの例：Claude Desktop に接続する

コネクター設定に移動する

ブラウザーで Claude を開き、設定ページに移動します。プロフィールアイコンをクリックし、ドロップダウンメニューから「設定」を選択するとアクセスできます。設定画面で、サイドバーの「コネクター」セクションを見つけてクリックします。現在設定されているコネクターが表示され、新しいコネクターを追加するオプションが利用できます。

Claude Desktop の設定ファイルを編集します：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

この例では、Openbridge API キーを使ってベアラートークンを使用する方法を示します。この設定を mcpServers セクションに追加します：

{
  "mcpServers": {
    "amazon_ads_mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://${HOSTNAME}:${PORT}/mcp/",
        "--allow-http",
        "--header",
        "Authorization:Bearer ${OPENBRIDGE_API_KEY}",
        "--header",
        "Accept:application/json,text/event-stream",
        "--debug"
      ],
      "env": {
        "HOSTNAME": "your_hostname",
        "PORT": "your_server_port",
        "MCP_TIMEOUT": "120000",
        "MCP_REQUEST_TIMEOUT": "60000",
        "MCP_CONNECTION_TIMEOUT": "10000",
        "MCP_SERVER_REQUEST_TIMEOUT": "60000",
        "MCP_TOOL_TIMEOUT": "120000",
        "MCP_REQUEST_WARNING_THRESHOLD": "10000",
        "OPENBRIDGE_API_KEY": "your_openbridge_token_here"
      }
    }
  }
}

注：hostname、port、your_openbridge_token_here を実際の OpenBridge トークンに置き換えてください。

重要：Cursor と Claude Desktop（Windows）には、npx の呼び出し時に args 内のスペースがエスケープされず、値が壊れてしまうバグがあります。次の方法で回避できます：mcp-remote のカスタムヘッダーに関するドキュメント。

設定は次のようになります：

{
  "mcpServers": {
    "amazon_ads_mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://${HOSTNAME}:${PORT}/mcp/",
        "--allow-http",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--header",
        "Accept: application/json, text/event-stream"
      ],
      "env": {
        "HOSTNAME": "your_hostname",
        "PORT": "your_server_port",
        "MCP_TIMEOUT": "120000",
        "MCP_REQUEST_TIMEOUT": "60000",
        "MCP_CONNECTION_TIMEOUT": "10000",
        "MCP_SERVER_REQUEST_TIMEOUT": "60000",
        "MCP_TOOL_TIMEOUT": "120000",
        "MCP_REQUEST_WARNING_THRESHOLD": "10000",
        "AUTH_HEADER": "Bearer <your_openbridge_token_here>"
      }
    }
  }
}

OAuth を使用している場合は、OPENBRIDGE_API_KEY が不要な次の例も使用できます：

{
  "mcpServers": {
    "amazon_ads_mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://localhost:9080/mcp/",
        "--allow-http"
      ],
      "env": {
        "MCP_TIMEOUT": "120000",
        "MCP_REQUEST_TIMEOUT": "60000",
        "MCP_CONNECTION_TIMEOUT": "10000",
        "MCP_SERVER_REQUEST_TIMEOUT": "60000",
        "MCP_TOOL_TIMEOUT": "120000",
        "MCP_REQUEST_WARNING_THRESHOLD": "10000"
      }
    }
  }
}

注：上記と同様のさまざまな Claude 設定については、最新の設定やオプションを記載した MCP Remote のドキュメントをご覧ください。

Claude Desktop を再起動する

設定ファイルを保存した後、Claude Desktop を再起動して新しい MCP サーバーを読み込みます。

⚠️ コンテキストの制限と有効な MCP サーバーツール

MCP ツールの登録と使用は、AI システムの利用制限に影響することがあります。利用制限は、Claude などの AI システムを一定期間内にどれだけ利用できるかを定めています。Anthropic の説明にあるように、使用する情報やデータの量は「会話の予算」を消費すると考えてください。この予算によって、制限がリセットされるまでに AI クライアントへ送信できるメッセージ数や、作業を続けられる時間が決まります。

MCP サーバーのツールは、タイトル、説明、ヒント、スキーマなどのメタデータをモデルのコンテキストに提供します。このメタデータは、短期的な作業メモリーとして機能する LLM のコンテキストウィンドウに読み込まれます。

Claude などの各クライアントには、固定サイズのコンテキストウィンドウがあります。これにより、ユーザープロンプト、システム指示、ツールのメタデータ、過去のメッセージなど、1 回のやり取りで処理できる情報量の上限が決まります。

有効にするツールが増えるほど、限られた領域が事前に多く消費されます。多数のツールを有効にすると、それらのスキーマと設定データが合わさってコンテキストを大きく消費し、コンテキストの上限にすぐ達することがあります。この場合、チャットの長さ制限を超えたことを示すエラーや警告が表示されます。

Amazon Ads MCP は API 全体を網羅しています。そのため、ツールが数百個に及ぶことがあります！

ツールが増えるほど、ユーザーとのやり取りに使える領域が減ります：不要なツールを有効にすると、実際のプロンプトやデータに使える領域が少なくなります。
少数から始めましょう：現在のタスクに必要なものだけを有効にします。必要になれば、後からいつでも追加できます。

予期しない長さの問題が発生した場合は、有効になっているツールを確認してください。使用していないツールを無効にすると、コンテキストの使用量を抑えられます。

コードモード

コードモードは、ツールのトークン消費量を大幅に削減する機能です。すべてのツールスキーマをあらかじめ LLM のコンテキストに読み込む代わりに、完全なカタログを 4 つの軽量なメタツールに置き換えます。LLM は必要に応じてツールを見つけ、サンドボックス化された Python を介して実行します。

トークンへの影響

モード	コンテキスト内のツール数	使用トークン数	コンテキストウィンドウ
標準	55	~32,000	16.1%
コードモード	4	~470	0.2%
削減率			98.6%

代表的なデフォルトサイズのカタログを用いた参考比較です。実際のツール数とトークン使用量は、AMAZON_AD_API_PACKAGES、サーバーのバージョン、トークナイザーによって異なります。

仕組み

コードモードでは、4 段階の探索パターンを使用します。

Stage 1: tags          → Browse categories: "campaign-management (20), accounts (14), ..."
Stage 2: search        → Find tools: search("campaigns") → cm_listCampaigns, cm_createCampaign, ...
Stage 3: get_schema    → Get parameters: get_schema("cm_listCampaigns") → full input schema
Stage 4: execute       → Run code: sandboxed Python with await call_tool("cm_listCampaigns", {...})

200 以上のすべてのツールに引き続きアクセスできます。LLM は、すべてのスキーマを最初に読み込むのではなく、必要に応じてツールを見つけて呼び出します。

コードモードの有効化

コードモードはデフォルトで CODE_MODE=true です。代わりにすべてのツールカタログをコンテキストに含めるには、次のように設定します。

CODE_MODE=false

Docker Compose — environment セクションに追加します。

environment:
  - CODE_MODE=false

Docker Run（ホストのポートをコンテナーの PORT にマッピングします。例：9080）：

docker run -d --env-file .env -e CODE_MODE=false -e PORT=9080 -p 9080:9080 amazon-ads-mcp:latest

ローカル開発（エントリーポイントは python -m amazon_ads_mcp.server で、MCP サーバーモジュールを実行します）：

CODE_MODE=false uv run python -m amazon_ads_mcp.server --transport http --port 9080

設定オプション

変数	デフォルト	説明
`CODE_MODE`	`true`	コードモードを有効にします
`CODE_MODE_INCLUDE_TAGS`	`true`	探索時にタグの参照を含めます（小規模なカタログでは `false` に設定します）
`CODE_MODE_MAX_DURATION_SECS`	`30`	サンドボックス実行ごとの最大実行時間
`CODE_MODE_MAX_MEMORY`	`50000000`	サンドボックス実行ごとのメモリー上限（50 MB）

コードモードの使用

有効にすると、MCP クライアント（Claude Desktop、Claude Code など）には、すべてのツールカタログではなく 4 つのツールのみが表示されます。

利用可能なカテゴリを参照する：

「利用できるツールカテゴリは何ですか？」

LLM は tags を呼び出し、campaign-management、sponsored-products、programmatic-dsp、accounts、reporting などのカテゴリを取得します。

特定のツールを検索する：

「キャンペーンの管理に使うツールを探してください」

LLM は search("campaigns") を呼び出し、一致するツール名と簡単な説明を取得します。

ツールの詳細を取得する：

「キャンペーンの作成に必要なパラメーターを表示してください」

LLM は get_schema("cm_CreateCampaign") を呼び出し、完全な入力スキーマを取得します。

操作を実行する：

「有効なキャンペーンを一覧表示してください」

LLM は Python コードを使って execute を呼び出します。

result = await call_tool("cm_QueryCampaign", {
    "body": {"stateFilter": {"include": ["ENABLED"]}}
})

ツールカテゴリ

LLM が tags を呼び出すと、API のプレフィックスに対応する、人が読みやすいカテゴリが表示されます。

カテゴリ	プレフィックス	説明
`campaign-management`	`cm`	キャンペーン、広告グループ、広告、ターゲットの作成、更新、検索、削除
`sponsored-products`	`sp`	スポンサープロダクトのターゲティング、キーワード、入札額
`sponsored-brands`	`sb`	スポンサーブランドのキャンペーン（v3 + v4）
`sponsored-display`	`sd`	スポンサーディスプレイのキャンペーンおよびターゲティング用ツール
`programmatic-dsp`	`dsp`	DSP 広告主、オーディエンス、コンバージョン、測定
`amazon-marketing-cloud`	`amc`	AMC のワークフロー、オーディエンス、管理
`accounts`	`ac`	プロファイル、請求、予算、ポートフォリオ、マネージャーアカウント
`reporting`	`rp`	V3 レポート用ツール
`brand-insights`	`br`	ブランドのベンチマークと指標
`stores`	`st`	ストアの分析
`server-management`	—	プロファイル、リージョン、OAuth、ダウンロード用ツール

コードモードを使用する場合

コードモードを使用する場合：

多くのツールパッケージを有効にしていて、コンテキスト制限に達している
会話やデータ分析に使えるコンテキスト領域を最大限に確保したい
MCP クライアントがツール探索パターンに対応している（Claude Desktop、Claude Code）

標準モードを使用する場合：

有効にしているパッケージが少数（1～3 個）
可能な限り速くツールを呼び出したい（探索ステップなし）
ワークフローで同じ少数のツールを繰り返し使用する

コードモードの確認

CODE_MODE=true を設定してサーバーを起動した後、次のように有効化されていることを確認します。

# Check server logs for confirmation
docker logs <container> 2>&1 | grep "Code mode"
# Expected: "Code mode active: 4 meta-tools exposed (tags, search, get_schema, execute)"

MCP クライアントに表示されるツールが tags、search、get_schema、execute の 4 つだけであることを確認してください。すべてのツールカタログが表示されている場合、コードモードは有効になっていません。環境変数を確認してください。

ツール監査

tool_audit を使用して、ツールカタログのトークン使用量とコードモードの動作を測定します。

ベースライン監査

.venv/bin/python -m amazon_ads_mcp.tool_audit \
  --url http://127.0.0.1:9080/mcp \
  --limit 20

JSON 出力：

.venv/bin/python -m amazon_ads_mcp.tool_audit \
  --url http://127.0.0.1:9080/mcp \
  --format json \
  --limit 0 \
  > /tmp/tool_audit.json

コードモードのプローブ監査

コードモードが有効な場合は、プローブモードを使用して、必要に応じたスキーマ取得のコストを推定します。

.venv/bin/python -m amazon_ads_mcp.tool_audit \
  --url http://127.0.0.1:9080/mcp \
  --format json \
  --limit 0 \
  --code-mode-probe \
  --probe-limit 50 \
  --probe-queries "campaign,ad,report,profile,dsp,amc,brand,targeting" \
  > /tmp/tool_audit_code_mode.json

簡易比較

jq '{tool_count,total_tool_tokens,context_window_percent}' /tmp/tool_audit.json
jq '{tool_count,total_tool_tokens,context_window_percent,code_mode_probe}' /tmp/tool_audit_code_mode.json

主なフィールド：

total_tool_tokens：tools/list による初期トークン読み込み量
context_window_percent：設定済みコンテキストウィンドウに占める割合
code_mode_probe.total_schema_tokens：コードモードでサンプリングしたスキーマ取得のトークンコスト合計
code_mode_probe.avg_schema_tokens：取得したスキーマあたりの平均トークンコスト

バックグラウンドタスク

Amazon Ads API の多くの操作は時間がかかります。レポートの生成、エクスポートの作成、AMC ワークフローの実行、オーディエンス処理、DSP 測定調査には、数秒から数分かかることがあります。バックグラウンドタスクを使うと、会話をブロックせずにこれらの操作を実行できます。

仕組み

バックグラウンドタスクはデフォルトで有効です。クライアントが任意のツールにバックグラウンド実行をリクエストすると、次のように動作します。

開始：ツールはタスク ID をすぐに返します
進捗の追跡：クライアントはサーバーが推奨する間隔でポーリングし、進捗の更新を確認します
結果の取得：タスクの完了後、クライアントは結果を取得します

サーバー内の非同期ツールはすべて、バックグラウンド実行を自動的にサポートします。フォアグラウンド（結果を待つ）でツールを実行するか、バックグラウンド（タスク ID を取得し、後でポーリングする）で実行するかは、クライアントが呼び出しごとに決定します。

組み込みのワークフローツール

これらのツールは、複数ステップのワークフロー（サーバー側ファイルのダウンロードと HTTP アクセス）を調整します。

ツール	目的
`download_export`	完了したエクスポートまたはレポートファイルを Amazon S3 からローカルストレージにダウンロードします
`list_downloads`	アクティブなプロファイルでダウンロードしたすべてのファイルを一覧表示します
`get_download_url`	ダウンロードしたファイルを取得するための HTTP URL を返します

これらのツールには進捗報告機能があり、クライアントはワークフローの各段階を追跡できます。

設定

変数	デフォルト	説明
`ENABLE_TASKS`	`true`	すべての非同期ツールでバックグラウンドタスクの実行を有効にします

バックグラウンドタスクを無効にするには：

ENABLE_TASKS=false

Docker Compose — environment セクションに追加します：

environment:
  - ENABLE_TASKS=false

バックエンド

サーバーはデフォルトでインメモリのタスクバックエンドを使用します。タスクはサーバープロセスの稼働中に追跡されます。サーバーが再起動すると、実行中のタスクは失われます。

再起動後もタスクの追跡を維持するには、Redis バックエンドを設定します。

FASTMCP_DOCKET_URL=redis://localhost:6379

プロンプトの例

タスク	プロンプトの例
レポートを生成する	「2026 年 3 月のスポンサープロダクト広告キャンペーンレポートを生成して」
キャンペーンをエクスポートする	「有効なキャンペーンをすべてエクスポートして」
AMC ワークフローを実行する	「過去 30 日間のオーディエンス重複ワークフローを実行して」

よくある質問

Kuudo が公開するのは Amazon Ads API の操作だけですか？

いいえ。このサーバーは Amazon Ads の操作そのものを公開します。Kuudo Skills はそれらを、複数の MCP サーバーのツールを組み合わせ、Agent Atlas を通じて Amazon やアカウントに関する知識を取得し、Agent Flow を使って独自のクラウドで永続的なデータ処理を行い、実行前に人間の承認を待つこともできる、再利用可能でバージョン管理された複数ステップの手順である、より高水準のワークフローにまとめます。Skills は、任意の MCP クライアント、コード、または CLI から実行できます。

あらかじめ用意された Skill を使う必要がありますか？

いいえ。エージェントは、単発の作業のためにこれらの操作を直接組み合わせられます。Skills は、繰り返し実行する手順を毎回同じ方法で実行したい場合に利用します。Skill を選んで実行を確認してから、アカウント用にフォークすることも、これらのツールを使って独自に作成することもできます。すべての Skill は、独自仕様ではない、プレーンなオープン形式のファイルです。

これが製品のすべてですか？

いいえ。このリポジトリは Amazon Ads のツールレイヤーです。Kuudo は、Selling Partner と Vendor Central 向けの MCP サーバー、Skills のワークフローレイヤー、ナレッジを扱う Agent Atlas、永続的なデータ処理を担う Agent Flow も運用しています。各要素の連携方法をご覧ください。

トラブルシューティング

サーバーに接続できませんか？

Docker コンテナが実行中であることを確認します：docker compose ps
サーバーのログを確認します：docker compose logs -f
ホストポートが .env の PORT と一致していることを確認します（.env.example では 9080 を使用しています。ポートの割り当ても一致させる必要があります）

認証エラーが発生しますか？

OpenBridge トークンが有効であることを確認します
トークンが環境に正しく設定されていることを確認します
Amazon Ads API へのアクセス権を確認します

Claude がサーバーを認識しませんか？

設定を変更した後、Claude Desktop を再起動します
MCP が有効になっていない場合は、Claude Desktop で「ページを再読み込み」を選択します
JSON の構文が正しいことを確認します
サーバー名が完全に一致していることを確認します

ドキュメント一覧

ドキュメント	目的
INSTALL.md	インストール、検証、アップグレード、開発環境のセットアップ
AGENTS.md	環境変数、Docker、MCP の調整、貢献ワークフロー
この README	概要、認証手順、ダウンロード、クライアント、コードモード
Kuudo MCP tool reference	Kuudo のすべての MCP サーバーとそのツール
Amazon Agent Skills	これらの操作を基盤とするワークフローレイヤー

📄 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

セキュリティ： このリポジトリの脆弱性は、GitHub の非公開セキュリティアドバイザリーから報告してください。

Smithery の掲載情報

ホストされたエンドポイント、API キーの設定、検出に必要な前提条件については、Smithery への公開をご覧ください。

Markdown 対応

ログインしてコメント

基本情報

作者: tspicer
言語: python
バージョン: 0.2.4
トランスポート: stdio
掲載日: 2026年2月3日
最終更新: 2 週間前
公式 Registry: io.github.tspicer/amazon_ads_mcp

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

amazon_ads_mcp

amazon_ads_mcp について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

Amazon Ads API MCP SDK

目次

Kuudo における位置づけ

MCP ツールとは？

🚀 Amazon Ads API MCP SDK とは？

✨ 主な機能

🎯 ユースケース

Claude Desktop との統合

AI アプリケーション

エンタープライズサービス

開発者ツール

この Ads MCP の特徴

こんな経験はありませんか

ここでは、間違った操作が正しい操作につながります

あらゆるケースがエッジケースです。ぜひご協力ください

クイックスタート

📚 Amazon Ads MCP には何が含まれていますか？

🧪 Amazon Ads API v1

MCP サーバーにとどまらない機能

インストール

設定

独自の Amazon Ads API アプリを持ち込む

1. Amazon にアプリケーションを登録する

OAuth フローを完了する

ステップ 1：OAuth を開始する

ステップ 2：Amazon Ads にリダイレクトする

ステップ 3：リクエストを承認する

ステップ 4：成功

ステップ 5：確認

パートナーアプリケーション：トークン認証

Openbridge Partner App

認証済み Amazon アカウント

Kuudo Partner App

Amazon Ads MCP パッケージを設定する

Amazon Ads MCP ツールについて

📥 レポートとエクスポートのダウンロード

レポートとエクスポートの違い

ワークフロー

プロンプトの例

HTTP ダウンロード API

プロファイルの分離

広告主プロファイルとリージョン

広告主プロフィールを設定する

アクティブリージョンを設定する

アクティブリージョンを取得する

MCP クライアントの例：Claude Desktop に接続する

Claude Desktop を再起動する

⚠️ コンテキストの制限と有効な MCP サーバーツール

コードモード

トークンへの影響

仕組み

コードモードの有効化

設定オプション

コードモードの使用

ツールカテゴリ

コードモードを使用する場合

コードモードの確認

ツール監査

ベースライン監査

コードモードのプローブ監査

簡易比較

バックグラウンドタスク

仕組み

組み込みのワークフローツール

設定

バックエンド

プロンプトの例

よくある質問

Kuudo が公開するのは Amazon Ads API の操作だけですか？

あらかじめ用意された Skill を使う必要がありますか？

これが製品のすべてですか？

トラブルシューティング