amazon_ads_mcp について
amazon_ads_mcp は Amazon Advertising API 向けの MCP サーバーで、Amazon Ads API MCP SDK と同じ README を持ちます。AI クライアントから広告 API を利用したい開発者を対象とし、複数リージョン対応と Docker によるデプロイに対応しています。
主な機能
- 01Model Context Protocol 対応
- 02NA、EU、FE のマルチリージョンエンドポイント
- 03キャンペーンとレポート API の対応
- 04Docker によるデプロイ
活用シーン
- 01AI クライアントからの広告レポートの照会
- 02AI アプリケーションからのキャンペーン管理
MCP 対応
本プロジェクトは MCP サーバーであり、Amazon Ads API の操作を MCP クライアントに公開します。
設定
リモートサーバーはインストール不要です。クライアントを選んで設定をコピーするか、ワンクリックで導入できます。
https://{HOSTNAME}/mcpclaude mcp add --transport http kuudoai-amazon-ads https://{HOSTNAME}/mcp{"mcpServers":{"kuudoai-amazon-ads":{"type":"http","url":"https://{HOSTNAME}/mcp"}}}Cursor で開く{"servers":{"kuudoai-amazon-ads":{"type":"http","url":"https://{HOSTNAME}/mcp"}}}VS Code で開く{"mcpServers":{"kuudoai-amazon-ads":{"type":"http","url":"https://{HOSTNAME}/mcp"}}}{"mcpServers":{"kuudoai-amazon-ads":{"serverUrl":"https://{HOSTNAME}/mcp"}}}コマンドはターミナルで実行し、JSON は各クライアントの MCP 設定に貼り付けて再起動します。認可が必要なサーバーは初回接続時にログインを求めます。
https://{HOSTNAME}/mcp認証が必要ツール
詳細
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-mcpcp .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"
サーバーで利用できるツールパッケージの一覧は次のとおりです。
profilestest-accountforecastsbrand-stores-managementcampaign-manageaccounts-manager-accountsaccounts-ads-accountsaccounts-portfoliosaccounts-billingaccounts-account-budgetsaudiences-discoveryreporting-version-3brand-benchmarksbrand-metricsstores-analyticssponsored-productssp-suggested-keywordssponsored-brands-v4sponsored-brands-v3sponsored-displaydsp-measurementdsp-advertisersdsp-audiencesdsp-conversionsdsp-target-kpi-recommendationsamazon-attributionaudience-insightspartner-opportunitiestactical-recommendationspersona-buildercreative-assetschange-historydata-provider-dataproducts-metadataproducts-eligibilityunified-pre-moderation-resultsmoderation-resultsamazon-marketing-streamlocationsexports-snapshotsmarketing-mix-modelingreach-forecastingamc-administrationamc-workflowamc-rule-audienceamc-ad-audienceads-api-v1-sp(ベータ)ads-api-v1-sb(ベータ)ads-api-v1-dsp(ベータ)ads-api-v1-sd(ベータ)ads-api-v1-st(ベータ)ads-api-v1-allads-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_→ キャンペーン/広告 APIamc_→ AMC 関連 APIdsp_→ DSP APIsd_→ Sponsored Displayams_→ Amazon Marketing Streamspv1_→ 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 への公開をご覧ください。
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。