メインコンテンツにスキップ

SparkX AI MCP 使用ガイド

SparkX AI の広告データを、お使いの AI アシスタントに接続し、自然言語での問い合わせ、分析、カスタムワークフローに利用できます。

SparkX AI MCP 使用ガイド

SparkX AI の広告データを、お使いの AI アシスタントに接続し、自然言語での問い合わせ、分析、カスタムワークフローに利用できます。

SparkX AI MCP は、SparkX AI プラットフォーム上の広告データを、お使いの AI アシスタントに接続します。設定後は、自然言語で広告パフォーマンス、エンティティ設定、操作ログを問い合わせることができます。また、SparkX AI データと自社のコスト、粗利、目標、その他の業務コンテキストを組み合わせて分析するよう AI に依頼できます。

現在のバージョンは、主にデータ問い合わせと分析に対応しています。AI アシスタントから広告エンティティを直接作成、変更、有効化、または一時停止することには対応していません。

1. MCP とは

MCP（Model Context Protocol）は、AI アシスタントが外部システムに接続するための標準プロトコルです。AI アシスタントが業務システムにアクセスするための標準的な接続方法と考えることができます。

API と比較すると、API はシステムや開発者向けのインターフェースに近いものです。システムを API で接続するには、通常、エンジニアが API ドキュメントを読み、コードを書き、認証を処理し、フィールドをマッピングする必要があります。MCP は API の機能を土台に、AI アシスタント向けのより標準化された接続方法を提供します。

SparkX AI は、プラットフォーム上のデータ取得機能を MCP Tools としてパッケージ化し、AI アシスタントは MCP プロトコルを通じてこれらの Tools を呼び出します。そのため、コードを書いたり、すべての API やフィールド名を覚えたりする必要はありません。自然言語で AI にデータの問い合わせと分析を依頼できます。

一言でいうと：

MCP is the USB-C of the AI world. We turn SparkX AI advertising capabilities into a standard connector, so your AI can plug in and use them.

2. SparkX AI MCP でできること

設定後、MCP に対応した AI アシスタントで以下を実行できます。

  • 自然言語で広告データを問い合わせる：例：「先週の各キャンペーンを ACOS の高い順に並べて」または「この商品ラインの直近 8 週間の TACOS 推移は？」

  • 自社の業務データと組み合わせて分析する：例：商品コスト、粗利率、在庫圧力、目標 ACOS を AI に提供し、SparkX AI の広告データに基づいて調整が必要なキャンペーンを判断する

  • 固定の分析ワークフローを再利用する：例：広告週報、月次レポート、商品診断、広告構造分析などのよく使うタスクを Skill 化し、毎回分析条件を説明する手間を減らす

  • 人間と AI の操作履歴を追跡する：例：特定キャンペーンの予算、入札、ターゲティング、Managed Group に関する最近の操作変更を確認する

  • AI Managed Group を管理する（書き込み権限が必要）：AI アシスタント上で Managed Group を作成、編集、削除し、目標 ACOS、管理目標、AI ステータス、アクションスペース、Managed Group 配下のキャンペーン紐付けを調整する

3. できること：問い合わせ + 管理

SparkX AI MCP は現在、3 種類のデータ問い合わせと AI Managed Group の管理に対応しています。

3.1 レポートおよびパフォーマンスデータ

広告パフォーマンス指標と一部のビジネス指標が含まれます。例：

  • インプレッション、クリック、広告費、売上、注文、販売ユニット数

  • ACOS、ROAS、クリック率（CTR）、コンバージョン率（CVR）、クリック単価（CPC）、注文あたりコスト

  • AI 管理基準の売上、ACOS、ROAS

  • ASIN レベルの総売上、TACOS、セッション、ページビュー、Buy Box 獲得状況など

3.2 エンティティ設定とメタデータ

広告アカウント内の主要なオブジェクトと設定が含まれます。例：

  • キャンペーン、広告グループ、ターゲティング、広告商品

  • ASIN タイトル、在庫、広告配信資格などの商品情報

  • Managed Group、商品ラインなどのグルーピング情報

3.3 操作ログ

人間と AI による広告オブジェクトへの操作記録が含まれます。例：

  • キャンペーン、広告グループ、ターゲティング、入札、予算、Managed Group の変更

  • 操作者、アクションタイプ、エンティティ、操作時間

  • AI 管理に関連する操作とパフォーマンス変化の追跡

3.4 AI Managed Group 管理

AI Managed Group の作成、編集、削除が含まれます。例：

  • AI Managed Group を作成する

  • 目標 ACOS、管理目標、AI ペルソナ、AI スイッチを調整する

  • アクションスペース（AI/RBA）を設定する

  • Managed Group 配下のキャンペーンを追加または削除する

4. はじめる前に

SparkX AI MCP を使用する前に、以下を確認してください。

  • SparkX AI プラットフォームアカウントが開通しており、問い合わせ対象のストアまたは広告アカウント権限があること

  • WorkBuddy、Claude、ChatGPT Codex、Cherry Studio、Coze など、MCP に対応した AI アシスタントがあること

5. SparkX AI MCP の設定方法

  • 認証方法を選択して MCP を接続します。OAuth を推奨しますが、MCP Token 方式も利用できます。

  • Skills をインストールして検証します。AI が Tools を正しく呼び出し、認可範囲を読み取れることを確認します。

  • 利用を開始します。自然言語で問い合わせ、分析し、認可済みの操作を実行します。

方式 A：OAuth 認可

OAuth は、この認可方式に対応したクライアントに適しています。MCP Token を作成、コピー、保管する必要はありません。接続時に SparkX AI にログインし、認可を確認するだけです。

  • ワンプロンプト設定：Claude、ChatGPT Codex、Cherry Studio、Coze、WorkBuddy など、AI が自分で MCP を設定できるクライアントでは、以下の文をそのまま送信します。

Please read the following GitHub repository and follow its instructions to configure SparkX AI MCP and install the Skills: https://github.com/SparkXAI/MCP
When authorization is required, open the sign-in page so I can complete the authorization.
After the configuration is complete, call get_user_authorized_context to verify the connection.

  • クライアントからログインまたは認可を求められたら、認可ページを開き、SparkX AI にログインして今回の接続を確認します。

  • 認可完了後、AI クライアントに戻ります。

Note：中国本土のお客様が Claude、特に Claude 個人版アカウントで SparkX MCP に接続する場合は注意してください。Anthropic の地域ポリシーの影響により、中国本土からの利用には一定の不確実性があり、Claude によって検知またはアカウント制限される可能性があります。中国本土のお客様には WorkBuddy または Codex の利用を推奨します。

方式 B：プラットフォームで Token を作成する

  • SparkX AI プラットフォームにログインし、MCP & Skill ページに移動します。

  • Create Token をクリックし、必要な認可範囲を選択して Token を作成します。

  • 生成された Token をコピーし、安全に保管します。

Note：ページを離れると、通常 Token は再表示できません。保存していない場合は、新しい Token を作成してください。

4. AI アシスタントで MCP を設定します

ワンプロンプトでの設定方法をおすすめします。MCP に対応した AI アシスタントを開き、以下の内容を AI に送信します。

Please read this GitHub repository and follow the instructions to configure SparkX AI MCP and install the Skills: https://github.com/SparkXAI/MCP
Token: <paste your Token>
After setup, call get_user_authorized_context to verify the connection.

AI アシスタントはリポジトリの手順に基づいて MCP を設定し、検証ツールを呼び出します。ユーザー情報と認可済みストアまたは Profile リストが返れば、設定は成功です。

方式 C：手動設定（上級者向け）

AI アシスタントが自動設定に対応していない場合は、MCP 設定でリモートサービスを手動で追加できます。

MCP サービス URL：

https://mcp.sparkx.cn/mcp

リクエストヘッダー：

Authorization: Bearer <your Token>

Claude Code CLI の例：

claude mcp add --transport http sparkx-mcp https://mcp.sparkx.cn/mcp --header "Authorization: Bearer <your Token>"

ChatGPT Codex の例：

[mcp_servers.sparkx-mcp]
url = "https://mcp.sparkx.cn/mcp"
bearer_token_env_var = "SPARKX_TOKEN"
http_headers = {}

AI アシスタントによって MCP 設定の入口は異なる場合があります。401 エラーが表示される場合は、Token が誤っている、または権限が不足している可能性があります。タイムアウトする場合は、まずネットワーク接続またはクライアントの MCP 設定を確認してください。

6. 質問のしかた

設定後は、自然言語で質問できます。より正確な結果を得るには、質問に以下を含めることをおすすめします。

  • 問い合わせ対象：ストア、キャンペーン、広告グループ、ASIN、商品ライン、Managed Group など

  • 期間：昨日、先週、直近 30 日、特定の暦月など

  • 指標：広告費、売上、ACOS、ROAS、TACOS、注文など

  • 出力形式：表、Top N、トレンド解釈、異常要因、アクション提案など

よく使う質問シナリオ：

6.1 アカウントまたはストアのヘルスチェック

日次でアカウント状態を確認する場合、または週次で全体パフォーマンスをレビューする場合に使用します。

Review this store's advertising performance last week. Summarize the main changes in spend, sales, ACOS, and ROAS, and point out the most important anomalies.

Compare the last 7 days with the previous 7 days. Which campaigns had the fastest spend increase? Did the increase bring sales growth?

6.2 キャンペーンまたは ASIN 診断

特定のキャンペーン、商品、商品ラインの問題を特定する場合に使用します。

Diagnose this ASIN's advertising performance over the last 30 days, focusing on spend, sales, ACOS, conversion rate, and inventory-related risks.

List campaigns from the last 14 days with ACOS above target and high spend, and provide prioritized recommendations.

6.3 検索語句とターゲティング分析

無駄な広告費、有望な語句、調整が必要なターゲティングを見つける場合に使用します。

Find search terms from the last 30 days with high spend and no orders, sorted by spend.

Which search terms had high ROAS but limited impressions or budget in the last 14 days? Provide a list of candidates for scaling.

6.4 商品ラインまたは広告構造分析

広告リソースの配分が合理的かを確認する場合に使用します。

Summarize ad spend, sales, ACOS, and TACOS by product line for the last 30 days, and identify which product lines are over- or under-allocated.

Analyze my ad structure by ad type and match type. Break down spend and output, and identify structural imbalance.

6.5 操作ログの追跡

パフォーマンス変化が人間または AI の操作と関係しているかを説明する場合に使用します。

ACOS increased for this campaign over the last 14 days. Check the related budget, bid, and targeting operation logs during the same period and identify possible causes.

List the main operations AI performed on managed groups in the last 7 days, and explain whether key metrics changed after those operations.

6.6 自社データと組み合わせて分析する

コスト、粗利、在庫、目標などの自社データがある場合は、会話内で AI に提供し、SparkX AI データと組み合わせて分析できます。

Here are my product costs and target gross margin rates. Combine them with ad spend and sales from the last 30 days, identify ASINs with poor actual profit performance, and provide adjustment recommendations.

The target TACOS for this product line this month is 12%. Based on current ad performance and total sales, should we control budget or increase investment?

6.7 週報、月報、固定テンプレート

同じ分析基準で定期的に結果を確認したい場合は、Skill または固定プロンプトを使用できます。

Generate last week's advertising report, including core KPIs, week-over-week changes, abnormal campaigns, Top movers, and recommendations for next week.

Generate last month's advertising report, including MoM and YoY comparison, ad structure, product performance, keyword performance, and target achievement.

7. Skill Hub を使用する

Skill は、再利用可能な分析手順のセットです。Skill をインストールすると、AI アシスタントは該当シナリオに合わせて、固定の手順でデータを取得し、分析し、結果を出力します。

7.1 公式 Skill

現在よく使う公式 Skill は以下のとおりです。

Skill

利用シーン

出力内容

Weekly Ad Report

週次の広告パフォーマンスレビュー

KPI の週次変化、7 日間トレンド、異常、Top リスト、翌週の提案

Monthly Ad Report

月次ビジネスレビュー

MoM と YoY 比較、広告グループ構造、商品およびキーワードのパフォーマンス、目標達成状況

Ad Structure Analysis

予算とトラフィック構造の確認

広告タイプ、配信方法などで広告費と成果を分解し、構造的な偏りを特定

Product Diagnosis

ASIN パフォーマンス問題の調査

ASIN ランキング階層、低パフォーマンス商品の特定、バリエーション比較、在庫と広告配信資格の確認

7.2 Skill をインストールする

通常、GitHub リポジトリの手順に沿って SparkX AI MCP を設定すると、AI アシスタントが必要な公式 Skills を直接インストールします。設定後、インストール済み Skill の一覧を確認するよう AI に依頼できます。

AI アシスタントが自動でインストールしない場合、または現在のクライアントで手動トリガーが必要な場合は、使用したい Skill を AI に直接伝えてください。例：

I want to install the Weekly Ad Report Skill.

または：

Help me install the official Skills for SparkX AI MCP.

AI アシスタントが手順に従ってインストールします。インストール後は、「Generate last week's advertising report」または「Help me run a product diagnosis」と入力できます。AI から Skill ファイルのアップロードまたは選択を求められた場合は、現在のクライアントの案内に従ってください。

7.3 独自の Skill を作成する

チームに固定の分析方法がある場合は、それをカスタム Skill として蓄積できます。作成時には以下を説明することをおすすめします。

  • 利用シーン：例：週次会議レビュー、目標達成確認、商品ライン予算確認

  • 問い合わせるデータ：例：キャンペーン、ASIN、検索語句、操作ログ

  • 分析手順：例：まず全体を見て、次に異常を確認し、原因を見て、最後に提案する

  • 出力形式：例：表、結論要約、アクション項目リスト

8. FAQ

Q1：SparkX MCP は顧客データにどのようにアクセスし、処理し、保護しますか？

SparkX MCP は、顧客の認可範囲内で、Claude、Codex、Cursor などの MCP 対応 AI クライアントに SparkX データ問い合わせ機能を提供します。データアクセスと処理方法は以下のとおりです。

アクセス範囲

MCP を接続しても、AI クライアントに SparkX アカウント全体が開放されるわけではありません。すべてのリクエストは SparkX の本人確認と権限チェックを通過する必要があります。実際にアクセスできる範囲は、現在のユーザー権限、MCP Token 権限、認可済み Profile によって共同で決まります。MCP Token がユーザーの既存のデータ権限を拡張することはありません。

SparkX MCP は、現在利用可能な Tools と MCP Token に付与された権限に応じて、データ読み取り機能と広告操作機能を提供できます。読み取り権限と書き込み権限は別々に管理されます。対応する書き込み権限がない場合、MCP は広告アカウントを変更できません。キャンペーン、予算、入札、その他の設定を変更する可能性があるリクエストでは、クライアントは実行予定の操作をユーザーに表示し、明示的な確認を得た後に実行する必要があります。

データ処理フロー

AI クライアントが実際に SparkX MCP Tool を呼び出す場合にのみ、そのリクエストに必要なパラメータと呼び出し情報が SparkX に送信されます。SparkX は権限チェックを完了した後、認可されたデータ問い合わせまたは広告操作を実行し、結果をクライアントに返します。MCP を接続しても、全量データ同期が開始されたり、広告操作が自動実行されたりすることはありません。また、MCP が接続されただけで、SparkX がユーザーと AI クライアントの会話全体を自動的に受け取ることもありません。

第三者 AI サービスによるデータ処理

Tool の結果が AI クライアントに返された後は、顧客が選択した AI クライアントとそのモデルサービスプロバイダーが引き続き処理します。関連データが保存されるか、どのくらい保持されるか、プロダクト改善やモデル学習に使用されるかは、そのサービスプロバイダーのプロダクトプラン、契約、プライバシーポリシー、アカウント設定によって異なり、SparkX が管理するものではありません。

企業顧客は、社内のセキュリティおよび法務チームが承認した AI サービスと企業アカウントを使用し、自社のデータガバナンス要件に従って、データ保持、モデル改善、データ共有オプションを設定してください。

Token セキュリティ

MCP Token はユーザー識別とアクセス権限の確認に使用されます。パスワードや API Key と同等のセキュリティレベルで管理してください。Token をチャット内容、ドキュメント、サポートチケットで送信しないでください。また、個人 Token を複数人で共有しないでください。Token が漏えいした、または不要になった場合は、SparkX で直ちに無効化または削除してください。

Q2：設定後に AI がデータを見つけられないのはなぜですか？

まず、AI に get_user_authorized_context を呼び出して認可情報を確認するよう依頼してください。認可済みストアまたは Profile が返らない場合は、Token が正しいか、有効期限が切れていないか、現在のアカウントに対象ストアまたは広告アカウント権限があるかを確認してください。

Q3：同じ質問でも、AI の出力が毎回完全には一致しないのはなぜですか？

MCP は問い合わせ可能なデータを提供し、最終的な分析は AI アシスタントが行います。AI アシスタントの種類、コンテキスト、質問の仕方が異なると、結論のまとめ方が変わる場合があります。質問では、期間、対象、指標、出力形式を明確に指定することをおすすめします。

Q4：MCP と InsightAgent はどのように使い分ければよいですか？

SparkX AI プラットフォーム内ですぐに使える分析結果を確認したい場合は、InsightAgent の利用をおすすめします。InsightAgent は、すぐに使える広告診断、異常分析、プラットフォーム内レビューに適しています。

自分の AI アシスタントで SparkX AI データを問い合わせたい場合、またはコスト、粗利、在庫、目標、社内表などの自社コンテキストと組み合わせて分析したい場合は、MCP の利用をおすすめします。MCP は、自由な追加質問、複数データソースをまたぐ分析、固定レポート生成、パーソナライズされたワークフローに適しています。

両者は代替関係ではなく、併用できます。InsightAgent はプラットフォーム内で標準的な結論を素早く得るのに適し、MCP は SparkX AI データを自社の AI ワークフローに持ち込み、さらに分析するのに適しています。

Q5：MCP と SparkX AI プラットフォームで直接レポートを見る場合の違いは何ですか？

プラットフォームレポートは、固定ダッシュボードと標準指標の確認に適しています。MCP は、自分の AI アシスタント内での自然言語問い合わせ、複数データソースをまたぐ分析、固定レポート生成、パーソナライズされた追加質問に適しています。両方を併用できます。

9. 付録：よく使う指標とオブジェクト

日常利用では、すべてのフィールド名を覚える必要はありません。自然言語で説明すれば十分です。以下は、指標やオブジェクトを正確に指定する必要がある場合の参考情報です。

9.1 よく使う指標

カテゴリ

指標例

トラフィック

インプレッション、クリック、広告費、AI 広告費

売上とコンバージョン

売上、注文、販売ユニット数、コンバージョン率

効率

ACOS、ROAS、クリック率、クリック単価、注文あたりコスト

新規顧客

新規顧客注文、新規顧客売上、新規顧客注文比率

商品詳細ページ

商品詳細ページビュー、商品詳細ページビュー率

AI 管理

AI 管理売上、AI 管理 ACOS、AI 管理 ROAS

ASIN ビジネス

総売上、TACOS、セッション、ページビュー、Buy Box 獲得状況

9.2 よく使う問い合わせ対象

対象

主な用途

キャンペーン

全体の予算、広告費、売上、効率を確認する

広告グループ

キャンペーン内部の構造とパフォーマンス差を分析する

ターゲティング

キーワード、商品ターゲティング、オーディエンスターゲティングのパフォーマンスを分析する

検索語句

高コンバージョン語句、無駄な広告費、新しい機会を見つける

広告商品

広告配信中 ASIN の広告パフォーマンスを確認する

ASIN

広告指標とビジネス指標を組み合わせて商品状態を分析する

Managed Group

AI 管理対象の設定、操作、パフォーマンス変化を確認する

商品ライン

業務グルーピング別に予算と売上貢献を確認する

9.3 操作ログのよく使うフィルター条件

条件

例

期間

直近 7 日、先週、特定の暦月

操作者

手動操作、AI 操作、特定ユーザー

操作対象

キャンペーン、広告グループ、ターゲティング、予算、入札、Managed Group

アクションタイプ

作成、更新、有効化、一時停止、予算調整、入札調整

関連記事
こちらの回答で解決しましたか？