Amazon Ads MCP

🚀 Amazon Ads API MCP SDK

Model Context Protocol (MCP) SDK for Amazon Advertising APIを使用して、AIベースの広告アプリケーションを構築しましょう

Openbridgeによる❤️ + ☕で作られました

🚀 クイックスタート

MCPツールとは何ですか？

MCP（Model Context Protocol）を、AIモデルと外部システム（Amazon Adsなど）の間の翻訳者だと考えてください。各MCPツールは、AIにAmazon Adsとのやり取り方法を教えるリモコンのボタンのようなものです。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を統合する
• エージェンシー管理システム：複数のクライアント、複数のアカウントの広告管理
• 電子商取引統合：Amazon Adsを電子商取引プラットフォームに接続する
• 分析ダッシュボード：リアルタイムの広告パフォーマンス監視

開発者ツール

• APIラッパー：特定のユースケースのためのカスタムSDKを作成する
• テストフレームワーク：Amazon Ads統合の自動テスト
• 開発ツール：ローカル開発とデバッグユーティリティ

📦 インストール

Amazon Ads API MCPのインストールは、🐳 Dockerを使用することをおすすめします。

docker pull openbridge/amazon-ads-mcp

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

cp .env.example .env

.envファイルを自分の設定で編集します。

Docker Composeでサーバーを起動します。

docker-compose up -d

サーバーは、http://localhost:9080 で利用できます。

ログを確認します。

docker-compose logs -f

サーバーを停止します。

docker-compose down

検証、アップグレード、および開発者セットアップを含む完全なインストール手順については、を参照してください。

設定

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に接続するには、2つの方法があります。

1. Bring Your Own App (BYOA)
2. パートナーアプリを利用する

独自のAmazon Ads APIアプリを使用する

独自のAmazon Ads APIアプリがある場合、または作成したい場合は、以下の手順で詳細が説明されています。

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

1. Amazon Developer Consoleにアクセスします。
2. Login with Amazonアプリケーションを作成または選択します。
3. Client IDとClient Secretをメモします。
4. コールバックURLを「許可された戻りURL」に設定します。これは、このサーバーを実行している場所です。
   • 本番環境用: https://your-server.com/auth/callback
   • ローカル開発用: http://localhost:8000/auth/callback

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

# Amazon Ads APIの資格情報 (必須)
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

例のプロンプト: "Set my current region to eu"

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

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

• ツール: start_oauth_flow
• 例のプロンプト: "Start my OAuth flow"

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

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

ステップ3: 要求を承認する

ブラウザウィンドウで、Amazonは接続要求を承認するように促します。

ステップ4: 成功

すべてがうまくいけば、成功応答が表示されます。ブラウザウィンドウを閉じて、クライアントに戻ることができます。他の何かが表示された場合は、プロセスを再度試行し、すべての構成要素が正しいことを確認してください。

ステップ5: 確認

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

• ツール: check_oauth_status
• 例のプロンプト: "Check my OAuth status"

これで、Amazon Ads APIシステムとのやり取りを開始する準備ができました！

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

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

Openbridgeパートナーアプリ

Ads APIパートナーアプリケーションプロバイダーとして、OpenbridgeはAmazon Ads APIへのすぐに使えるゲートウェイを提供します。Openbridgeアカウントにログインし、トークンをプロビジョニングしてから、クライアント構成でトークンを設定します（以下を参照）。

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

AUTH_METHOD=openbridge

これでサーバー構成は完了です。サーバーにアクセスするには、Claude Desktopなどのクライアントを構成して、トークンを直接渡す必要があります。（Example MCP Client: Connect Claude Desktopを参照）

承認されたAmazonアカウント

Amazonの承認情報はOpenbridgeに保存されています。クライアントで最初に行うことは、現在のIDを要求することです。"List my remote identities"と入力します。次に、MCPサーバーにこれらのIDの1つを使用するように指示します。"Set my remote identity to <>"と入力します。その後、MCPにList all of my Amazon Ad profilesを要求して、そのアカウントにリンクされたすべてのAmazon広告プロファイルを一覧表示することができます。広告主が表示されない場合は、別のIDを設定してください。

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

アクティブにするには、ロードするパッケージをカンマ区切りで設定する必要があります。たとえば、profilesとamc-workflowをアクティブにするには、以下のようにパッケージ環境を設定します。

• AMAZON_AD_API_PACKAGES="profiles,amc-workflow"

サーバーで利用可能なツールパッケージのリストは以下の通りです。

• profiles
• 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
• forecasts
• brand-store-manangement
• partner-opportunities
• tactical-recommendations
• persona-builder
• creative-assets
• change-history
• data-provider-data
• data-provider-hashed
• 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

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

Amazon Ads MCPツールの理解

Amazon Ads MCPツールには、特定の広告API操作を整理するための接頭辞（たとえば、キャンペーンパフォーマンスの場合はcp_、Amazon Marketing Cloudの場合はamc_）が付いています。

例の接頭辞:

• cp_ → キャンペーン/広告API
• amc_ → AMC関連のAPI
• dsp_ → DSP API
• sd_ → Sponsored Display
• ams_ → Amazon Marketing Stream

これは、利用可能なAPI操作に対応するツールのコレクションに変換されます。

キャンペーン管理 (cp_)

• cp_listCampaigns — すべてのキャンペーンを一覧表示する
• cp_getCampaign — 特定のキャンペーンを取得する
• cp_createCampaign — 新しいキャンペーンを作成する
• cp_updateCampaign — キャンペーンを更新する
• cp_archiveCampaign — キャンペーンをアーカイブする

スポンサードプロダクト (sp_)

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

AMCワークフロー (amc_)

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

ユーザーは、次のようなツールを見ることができます。

• "List my Amazon Ads campaigns"
  → Claudeは: cp_listCampaignsを使用します。
• "Create an AMC workflow"
  → Claudeは: amc_createWorkflowを使用します。
• "Export my sponsored products ads data"
  → Claudeは: export_createAdExportを使用します。

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

広告主プロファイルを設定する

Amazonによると、プロファイルは、Amazon Ads APIで特定の呼び出しの管理範囲を決定する上で重要な役割を果たします。プロファイルIDは、特定のマーケットプレイスで広告主のデータとサービスにアクセスするために必要な資格情報です。

承認によってアクセスできるプロファイルがわからない場合があります。承認によってアクセスできるすべての広告プロファイルを一覧表示することができます。

• ツール: ac_listProfiles
• 例のプロンプト: "List my advertiser profile ids"

応答には、以下のプロファイル詳細が含まれています。

• profileId、countryCode、currencyCode
• dailyBudget、timezone
• accountInfo (type: seller/vendor/agency)

リストにプロファイルID 1043817530956285が含まれていると仮定します。これが使用したいプロファイルであることを確認するために、プロファイルの詳細を取得できます。

• ツール: ac_getProfile
• 例のプロンプト: "Get the details for my profile_id: 1043817530956285"

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

• ツール: set_active_profile
• 例のプロンプト: "Set my active profile id to 1043817530956285"

プロファイルを設定すると、以下が決定されます。

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

プロファイルIDは、セッションの間、バックグラウンドで設定されます。新しいプロファイルに切り替えたい場合は、このプロセスを繰り返します。

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

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

• ツール: set_active_profile

例のプロンプト: "Set my active advertiser profile to 111111111111"

プロファイルID 111111111111がnaに関連付けられている場合、リージョンはプロファイルのリージョンに基づいて設定されます。

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

Amazon Ads MCPサーバーには、APIリージョンをデフォルトとして、または動的に管理するツールが含まれており、サーバーを再起動することなく、北米（na）、ヨーロッパ（eu）、および極東（fe）のリージョンを切り替えることができます。

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

1. APIエンドポイントを更新する - API呼び出しを正しいリージョンのエンドポイントにルーティングする
2. OAuthエンドポイントを更新する - リージョンに適したトークン更新エンドポイントを使用する
3. キャッシュされたトークンをクリアする - 新しいリージョンでの新鮮な認証を確保する
4. その他の設定を保持する - プロファイルIDとアイデンティティ設定をそのままにする

重要: リージョンの不一致を避ける: 広告主プロファイルに関連付けられていないリージョンを設定しようとすると、Ads APIは要求を拒否します。たとえば、プロファイルIDがnaに関連付けられている場合に、手動でリージョンをeuに設定すると、不一致が発生し、API要求が失敗します。

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

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

• ツール: get_active_region
• 返される情報: 現在のリージョン、エンドポイント、および構成ソース

例のプロンプト: "What is my current active region?"

例のMCPクライアント: Claude Desktopを接続する

1. コネクタ設定に移動する

ブラウザでClaudeを開き、設定ページに移動します。これは、プロファイルアイコンをクリックして「Settings」を選択することでアクセスできます。設定ページで、サイドバーの「Connectors」セクションを見つけてクリックします。これにより、現在構成されているコネクタが表示され、新しいコネクタを追加するオプションが提供されます。

2. 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_REFRESH_TOKEN}",
        "--header",
        "Accept:application/json,text/event-stream",
        "--debug"
      ],
      "env": {
        "MCP_TIMEOUT": "300",
        "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_REFRESH_TOKEN": "your_openbridge_token_here"
      }
    }
  }
}

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

重要: CursorとClaude Desktop（Windows）には、npxを呼び出すときに引数内のスペースがエスケープされないバグがあり、これらの値が破損します。これを回避するには、mcp-remote custom headers documentationを使用します。

構成は次のようになります。

{
  "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": {
        "MCP_TIMEOUT": "300",
        "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_REFRESH_TOKENが必要ないため、次の例を使用できます。

{
  "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 docsを参照してください。

3. Claude Desktopを再起動する

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

⚠️ コンテキスト制限とアクティブなMCPサーバーツール

MCPツールの登録と使用は、AIシステムの使用制限に影響を与える可能性があります。使用制限は、特定の期間にClaudeなどのAIシステムとどれだけやり取りできるかを制御します。Anthropicが述べているように、使用する情報/データの量を「会話予算」から引き落とすように考えてください。この予算は、AIクライアントに送信できるメッセージの数、または制限がリセットされるまでに作業できる時間を決定します。

MCPサーバーツールは、タイトル、説明、ヒント、およびスキーマなどのメタデータをモデルのコンテキストに追加します。このメタデータは、LLMのコンテキストウィンドウにロードされ、これはその短期的な作業メモリとして機能します。

Claudeなどの各クライアントには、固定サイズのコンテキストウィンドウがあります。これは、ユーザープロンプト、システム指示、ツールメタデータ、および以前のメッセージを含む、単一のインタラクションで処理できる最大情報量を定義します。

アクティブにするツールが多いほど、その限られたスペースが最初から多く消費されます。多くのツールをアクティブにすると、それらの組み合わせたスキーマと構成ペイロードがこのコンテキストを大幅に消費し、すぐにコンテキストの上限に達する可能性があります。このとき、チャットの長さ制限を超えたというエラーや警告が表示され始めます。

Amazon Ads MCPは、API全体を網羅しています。その結果、100以上のツールが存在する可能性があります！

• ツールが多いほど、ユーザーとのインタラクションの余地が少なくなる: 不要なツールをアクティブにすると、実際のプロンプトやデータのための利用可能なスペースが減少します。
• 少ないツールから始める: 現在のタスクに必要なものだけをアクティブにします。後で必要に応じて追加することができます。

予期しない長さの問題が発生している場合は、アクティブなツールを確認してください。使用していないツールを削除すると、コンテキストの使用を最小限に抑えるのに役立ちます。

トラブルシューティング

サーバーに接続できない場合

• Dockerコンテナが実行中であることを確認します。docker-compose ps
• サーバーログを確認します。docker-compose logs -f
• ポートが正しいことを確認します（デフォルトでは8765）

認証エラーの場合

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

Claudeがサーバーを認識しない場合

• 構成を変更した後、Claude Desktopを再起動します。
• MCPがアクティブでない場合は、Claude Desktopで「ページを再読み込み」します。
• JSON構文が正しいことを確認します。
• サーバー名が正確に一致することを確認します。

📄 ライセンス

このプロジェクトは、MITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。