SparkX AI MCP 可以把 SparkX AI 平台中的广告数据连接到您常用的 AI 助手中。配置完成后，您可以直接用自然语言查询广告表现、实体配置和操作日志，也可以让 AI 把 SparkX AI 数据与您自己的成本、毛利、目标或其他业务背景结合起来分析。

当前版本主要支持数据查询与分析，不支持在 AI 助手中直接创建、修改或启停广告实体。

1. 什么是 MCP

MCP（Model Context Protocol）是一种让 AI 助手连接外部系统的标准协议。您可以把它理解为 AI 助手访问业务系统的标准连接方式。

如果用 API 来对比，API 更像是给系统或开发者使用的接口：每接入一个系统，通常需要工程师阅读接口文档、写代码、处理鉴权和字段映射。MCP 则是在 API 能力之上，为 AI 助手提供一套更标准的连接方式。

SparkX AI 先把平台中的取数能力封装成 MCP Tool，AI 助手再按 MCP 协议调用这些 Tool。这样用户不用自己写代码，也不用记住每个接口和字段，就可以直接用自然语言让 AI 查询和分析数据。

可以说：

MCP 是 AI 世界的 USB-C；我们把SparkX AI的广告能力成了标准插头，您的 AI 插上就能用

2. SparkX AI MCP 可以做什么

配置完成后，您可以在支持 MCP 的 AI 助手中完成以下操作：

用自然语言查询广告数据：例如“上周各广告活动按 ACOS 从高到低排序”或“这个产品线最近 8 周的 TACOS 趋势如何”。
结合自有业务数据分析：例如把产品成本、毛利率、库存压力或目标 ACOS 提供给 AI，让它结合 SparkX AI 的广告数据判断哪些广告活动需要调整。
复用固定分析流程：例如把广告周报、月报、商品诊断、广告结构分析等常用任务沉淀为 Skill，减少每次重新描述分析口径的成本。
追溯人工与 AI 操作记录：例如查看某个广告活动近期预算、竞价、投放或托管组相关的操作变更。
管理 AI 托管组（需要写权限）——在 AI 助手里创建、编辑、删除托管组，调整目标 ACOS、托管目标、AI 状态、行动空间，以及托管组下广告活动的绑定关系。

3. 你能做什么：查询 + 管理

SparkX AI MCP 当前支持查询三类数据，并进行AI托管组管理。

3.1 报表与效果数据

包括广告表现指标和部分业务指标，例如：

曝光量、点击量、花费、销售额、订单数、销量
ACOS、ROAS、点击率（CTR）、转化率（CVR）、点击成本（CPC）、订单成本
AI 托管口径下的销售额、ACOS、ROAS
ASIN 维度下的总销售额、TACOS、会话次数、页面浏览量、购物车占有率（Buy Box）等

3.2 实体配置与元数据

包括广告账户中的主要对象与配置，例如：

广告活动、广告组、投放、推广商品
ASIN 标题、库存、广告投放资格等商品信息
托管组、产品线等分组信息

3.3 操作日志

包括人工和 AI 对广告对象的操作记录，例如：

广告活动、广告组、投放、出价、预算、托管组的变更
操作者、动作类型、实体对象、操作时间
AI 托管相关的操作与效果变化追溯

3.4 AI托管组管理

包括创建、编辑、删除AI托管组，例如

创建AI托管组
调整目标 ACOS、托管目标、AI 人格、AI 开关
配置行动空间（AI/RBA）
添加或移除托管组下的广告活动

4. 使用前准备

使用 SparkX AI MCP 前，请确认您已具备以下条件：

已开通 SparkX AI 平台账号，并拥有需要查询的店铺或广告账户权限。
拥有一个支持 MCP 的 AI 助手，例如 WorkBuddy、Claude、ChatGPT Codex、Cherry Studio、Coze 等。

5. 如何配置 SparkX AI MCP

选择授权方式并连接 MCP——推荐使用 OAuth，也保留 MCP Token 方式。
安装 Skills 并验证——确认 AI 能正确调用工具并读取授权范围。
开始使用——用自然语言查询、分析和执行已授权的操作。

选择授权方式并连接 MCP

方式 A · OAuth 授权

OAuth 适合支持该授权方式的客户端。你不需要创建、复制或保管 MCP Token；连接时登录 SparkX AI 并确认授权即可。

一句话配置：在能让 AI 自己动手配置的客户端里（Claude、ChatGPT Codex、Cherry Studio、扣子 Coze、WorkBuddy 等），直接把下面这段发给它

请阅读以下 GitHub 仓库，并按说明配置 SparkX AI MCP 和安装 Skills：
https://github.com/SparkXAI/MCP
需要授权时，请打开登录页面让我完成授权。
配置完成后，请调用 get_user_authorized_context 验证。

客户端提示登录或授权时，打开授权页面，登录 SparkX AI，确认本次连接。
授权完成后返回 AI 客户端。

特别说明：国内客户，谨慎使用Claude（尤其是Claude个人版账号）链接SparkX MCP，受限于 Anthropic 的地域政策，国内使用过程中存在一定的不确定性，有概率被Claude识别或封号，建议推荐国内客户使用Workbuddy / Codex 等

方式 B · 页面创建 Token

登录 SparkX AI 平台，进入 MCP & Skill 页面。
点击 新建 Token，按需要选择授权范围并创建 Token。
复制生成的 Token 并妥善保存。

注意：Token 离开页面后通常无法再次查看。如未保存，请重新生成。

4. 在 AI 助手中配置 MCP

推荐使用一句话配置方式。打开支持 MCP 的 AI 助手后，将下面这段内容发送给 AI：

请阅读这个 GitHub 仓库，并按里面的说明帮我配置 SparkX AI MCP 和安装 Skills：
https://github.com/SparkXAI/MCP
Token：<粘贴您的 Token>
配置完成后，请调用 get_user_authorized_context 验证。

AI 助手会根据仓库中的说明完成 MCP 配置，并调用验证工具。如果返回您的用户信息和已授权的店铺或 Profile 列表，说明配置成功。

方式 C·手动配置方式（升级玩法）

如果您的 AI 助手不支持自动配置，可以在 MCP 设置中手动添加远程服务。

MCP 服务地址：

https://mcp.sparkx.cn/mcp

请求头：

Authorization: Bearer <您的 Token>

Claude Code CLI 示例：

claude mcp add --transport http sparkx-mcp https://mcp.sparkx.cn/mcp --header "Authorization: Bearer <您的 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、产品线、托管组等
时间范围：昨天、上周、最近 30 天、某个自然月等
需要的指标：花费、销售额、ACOS、ROAS、TACOS、订单数等
输出格式：表格、Top N、趋势解读、异常原因、行动建议等

一些常用提问场景如下：

6.1 账户或店铺体检

可用于每日查看账户状态，或每周复盘整体表现。

帮我看一下上周这个店铺的广告表现，按花费、销售额、ACOS、ROAS 总结主要变化，并指出最需要关注的异常。

对比最近 7 天和前 7 天，哪些广告活动的花费增长最快？这些增长是否带来了销售额提升？

6.2 广告活动或 ASIN 诊断

可用于定位某个广告活动、商品或产品线的问题。

请诊断这个 ASIN 最近 30 天的广告表现，重点看花费、销售额、ACOS、转化率和库存相关风险。

列出最近 14 天 ACOS 高于目标且花费较高的广告活动，并按优先级给出处理建议。

6.3 搜索词和定向分析

可用于发现浪费花费、潜力词或需要调整的定向。

帮我找出最近 30 天花费高但没有订单的搜索词，并按花费排序。

最近 14 天有哪些搜索词 ROAS 较高但曝光或预算不足？请给出可放量的候选列表。

6.4 产品线或广告结构分析

可用于检查广告资源分配是否合理。

按产品线汇总最近 30 天的广告花费、销售额、ACOS 和 TACOS，判断哪些产品线预算占比过高或过低。

分析我的广告结构，按广告类型和匹配类型拆解花费与产出，指出结构失衡的地方。

6.5 操作日志追溯

可用于解释效果变化是否与人工或 AI 操作有关。

这个广告活动最近 14 天 ACOS 上升了，请查看同期预算、竞价和投放相关的操作日志，判断可能原因。

请列出最近 7 天 AI 对托管组做过的主要操作，并说明这些操作之后关键指标是否有明显变化。

6.6 结合自有数据分析

如果您有成本、毛利、库存、目标等自有数据，可以在对话中提供给 AI，再让 AI 结合 SparkX AI 数据分析。

以下是我的产品成本和目标毛利率。请结合最近 30 天广告花费和销售额，判断哪些 ASIN 实际利润表现不好，并给出调整建议。

这个产品线本月目标 TACOS 是 12%。请结合当前广告表现和总销售额，判断是否需要控制预算或加大投放。

6.7 周报、月报和固定模板

如果您希望定期获得同一套分析口径，可以使用 Skill 或固定提示词。

请生成上周广告周报，包括核心 KPI、环比变化、异常广告活动、Top 变化榜和下周建议。

请生成上个月广告月报，包含 MoM 和 YoY 对比、广告结构、商品表现、关键词表现和目标达成情况。

7. 使用 Skill Hub

Skill 是一套可复用的分析说明。安装 Skill 后，AI 助手会在对应场景中按照固定步骤取数、分析并输出结果。

7.1 官方 Skill

当前常用的官方 Skill 包括：

Skill	适用场景	输出内容
广告数据周报	每周复盘广告表现	KPI 环比、7 天趋势、异常变化、Top 榜单、下周建议
广告数据月报	月度经营复盘	MoM 与 YoY 对比、广告组结构、商品与关键词表现、目标达成情况
广告结构分析	检查预算和流量结构	按广告类型、投放方式等拆解花费与产出，识别结构失衡
商品诊断	排查 ASIN 表现问题	ASIN 排名分层、低效商品识别、变体对比、库存与投放资格检查

7.2 安装 Skill

一般情况下，当您按 GitHub 仓库中的说明配置 SparkX AI MCP 时，AI 助手会直接帮您安装所需的官方 Skills。配置完成后，您可以让 AI 确认已安装的 Skill 列表。

如果 AI 助手没有自动安装，或当前客户端需要手动触发安装，您可以直接告诉 AI 想使用的 Skill，例如：

我要安装广告数据周报 Skill。

或：

帮我把 SparkX AI MCP 的官方 Skills 装上。

AI 助手会根据提示完成安装。安装后，您可以直接说“生成上周广告周报”或“帮我做商品诊断”。如果 AI 提示需要上传或选择 Skill 文件，请按照当前客户端的引导完成安装。

7.3 创建自己的 Skill

如果您的团队有固定分析方法，也可以把它沉淀为自定义 Skill。建议在创建时说明：

适用场景：例如周会复盘、目标达成检查、产品线预算检查
需要查询的数据：例如广告活动、ASIN、搜索词、操作日志
分析步骤：例如先看总览，再看异常，再看原因，再给建议
输出格式：例如表格、结论摘要、行动项清单

8. 常见问题

Q1：SparkX MCP 如何访问、处理和保护客户数据？

SparkX MCP 在客户授权范围内，为 Claude、Codex、Cursor 等支持 MCP 的 AI 客户端提供 SparkX 数据查询能力。其数据访问和处理方式如下。

访问范围

连接 MCP 不会向 AI 客户端开放整个 SparkX 账户。每次请求都需要通过 SparkX 的身份和权限校验，实际可访问范围由当前用户权限、MCP Token 权限及已授权 Profile 共同决定。MCP Token 不能扩大用户原有的数据权限。

SparkX MCP 可提供数据读取和广告操作能力，具体取决于当前已上线的工具以及 MCP Token 获得的权限。读取权限和写入权限分开控制；未获得对应写入权限时，MCP 不能修改广告账户。对于可能改变广告活动、预算、出价或其他配置的请求，客户端需要向用户展示拟执行的操作，并在获得明确确认后执行。

数据处理流程

只有当 AI 客户端实际调用 SparkX MCP 工具时，客户端才会将完成该次请求所需的参数和调用信息发送至 SparkX 。SparkX 完成权限校验后执行获准的数据查询或广告操作，并将结果返回给客户端。连接 MCP 本身不会触发全量数据同步或自动执行广告操作，SparkX 也不会仅因为 MCP 已连接而自动接收用户与 AI 客户端的全部对话。

第三方 AI 服务的数据处理

工具返回结果进入 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、会话次数、页面浏览量、购物车占有率

9.2 常见查询对象

对象	常见用途
广告活动	查看整体预算、花费、销售和效率表现
广告组	分析广告活动内部结构和表现差异
投放	分析关键词、商品投放或受众定向表现
搜索词	发现高转化词、浪费花费词和新增机会
推广商品	查看被推广 ASIN 的广告表现
ASIN	结合广告与业务指标分析商品健康度
托管组	查看 AI 托管对象的配置、操作和效果变化
产品线	按业务分组查看预算与销售贡献

9.3 操作日志常见筛选条件

条件	示例
时间范围	最近 7 天、上周、某个自然月
操作者	人工操作、AI 操作、指定用户
操作对象	广告活动、广告组、投放、预算、竞价、托管组
动作类型	创建、更新、启用、暂停、预算调整、出价调整

SparkX AI MCP 使用指南