amazonads-mcp

Amazon Ads MCP サーバー

Amazon Advertising API と連携するためのツールを提供する Model Context Protocol（MCP）サーバーです。このサーバーにより、AI アシスタントは Amazon Ads のキャンペーン、キーワード、パフォーマンスデータなどにアクセスし、管理できます。

機能

この MCP サーバーは、以下のツールを提供します。

• get_profiles：利用可能な Amazon Ads のプロフィール／アカウントをすべて一覧表示します
• get_campaigns：状態やタイプで任意に絞り込んで広告キャンペーンを取得します
• get_campaign_performance：キャンペーンのパフォーマンス指標（インプレッション数、クリック数、費用、売上）を取得します
• get_keywords：キャンペーンまたは広告グループのキーワードを取得します
• update_keyword_bid：特定のキーワードの入札額を更新します
• create_campaign：新しい広告キャンペーンを作成します
• get_product_ads：キャンペーンまたは広告グループの商品広告を取得します

前提条件

1. Amazon Ads アカウント：有効な Amazon Ads アカウントが必要です
2. API 認証情報：Amazon Ads API の利用を登録し、以下を取得してください。
   • Client ID
   • Client Secret
   • Refresh Token

Amazon Ads API 認証情報の取得

ステップ 1：アプリケーションを登録する

1. Amazon Advertising API にアクセスします
2. Amazon Ads アカウントでサインインします
3. Developer Center に移動し、新しいアプリケーションを作成します
4. Client ID と Client Secret が発行されるので、保存してください。

ステップ 2：Refresh Token を取得する

OAuth フローで Refresh Token を取得するためのヘルパースクリプトを用意しています。

1. プロジェクトのルートに .env ファイルを作成します。

   AMAZON_ADS_CLIENT_ID=your_client_id_here
   AMAZON_ADS_CLIENT_SECRET=your_client_secret_here
   

2. OAuth ヘルパースクリプトを実行します。

   npm run get-token
   

3. ブラウザーで Amazon の認証ページが開きます

4. サインインして、アプリケーションを認証します

5. スクリプトに Refresh Token が表示されます。これを .env ファイルにコピーしてください

ステップ 3：リージョンを確認する

広告を配信するリージョンを確認します。

• NA：北米（amazon.com）
• EU：ヨーロッパ（amazon.co.uk、amazon.de など）
• FE：極東（amazon.co.jp など）

インストール

1. このリポジトリをクローンします。

git clone <your-repo-url>
cd amazonads-mcp

2. 依存関係をインストールします。

npm install

3. プロジェクトをビルドします。

npm run build

設定

環境変数

.env ファイルを作成するか、以下の環境変数を設定します。

AMAZON_ADS_CLIENT_ID=your_client_id
AMAZON_ADS_CLIENT_SECRET=your_client_secret
AMAZON_ADS_REFRESH_TOKEN=your_refresh_token
AMAZON_ADS_REGION=NA  # Options: NA, EU, FE
AMAZON_ADS_SANDBOX=false  # Set to true for testing with sandbox API

Claude Desktop の設定

このサーバーを Claude Desktop の設定ファイルに追加します。

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

{
  "mcpServers": {
    "amazonads": {
      "command": "node",
      "args": ["/absolute/path/to/amazonads-mcp/build/index.js"],
      "env": {
        "AMAZON_ADS_CLIENT_ID": "your_client_id",
        "AMAZON_ADS_CLIENT_SECRET": "your_client_secret",
        "AMAZON_ADS_REFRESH_TOKEN": "your_refresh_token",
        "AMAZON_ADS_REGION": "NA"
      }
    }
  }
}

使用例

Claude Desktop で設定すると、Claude に次のように依頼できます。

• 「Amazon Ads のキャンペーンをすべて表示して」
• 「1 月 1 日から 1 月 31 日までのキャンペーン ID 12345 のパフォーマンス指標を教えて」
• 「キャンペーン 12345 のキーワードをすべて一覧表示して」
• 「キーワード 67890 の入札額を $1.50 に更新して」
• 「1 日あたり $50 の予算で新しい Sponsored Products キャンペーンを作成して」
• 「キャンペーン 12345 の商品広告をすべて表示して」

開発

プロジェクト構成

amazonads-mcp/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   └── amazon-ads-client.ts  # Amazon Ads API client
├── build/                     # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

ビルド

npm run build

開発モード

変更を監視して、自動的に再ビルドします。

npm run watch

サーバーのテスト

サーバーを直接実行します。

npm start

サーバーは stdio 経由で通信し、MCP プロトコルメッセージを受け取ります。

API の対応状況

このサーバーは現在、以下に対応しています。

• Sponsored Products：キャンペーン、キーワード、商品広告を完全にサポート
• Sponsored Brands：キャンペーン管理（一部サポート）
• Sponsored Display：キャンペーン管理（一部サポート）
• レポート：基本的なパフォーマンス指標（簡易実装）

重要な注意事項

1. レート制限：Amazon Ads API にはレート制限があります。クライアントには現在、レート制限のロジックが実装されていません。

2. レポート API：get_campaign_performance ツールでは、簡易的な実装を使用しています。本番環境で使用する場合は、次の完全な非同期レポートフローを実装してください。

   • レポートリクエストを作成する
   • レポートが完了するまでポーリングする
   • レポートをダウンロードして解析する

3. エラー処理：API エラーは呼び出し元に返されます。認証エラーを回避するため、認証情報を適切に設定してください。

4. リージョン：Amazon Ads アカウントに応じて、正しいリージョン（NA、EU、FE）を設定してください。

セキュリティ

• .env ファイルをコミットしたり、API 認証情報を公開したりしないでください
• リフレッシュトークンは安全に保存してください
• 本番環境での使用にあたっては、認証情報のローテーションの実装を検討してください

リソース

• Amazon Ads API のドキュメント
• Model Context Protocol のドキュメント
• MCP TypeScript SDK

ライセンス

MIT

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストをお送りください。