跳转到主要内容

Xnurta MCP 使用指南

将 Xnurta 的广告数据接入您的 AI 助手，支持自然语言查询、分析和自定义工作流。

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

当前版本支持数据查询、AI 托管组管理、广告实体编辑和 SP 广告活动创建。写操作需要对应权限，并在要求确认的操作中由您明确确认后执行。

1. 什么是 MCP

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

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

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

可以说：

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

2. Xnurta MCP 可以做什么

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

  • 用自然语言查询广告数据：例如“上周各广告活动按 ACOS 从高到低排序”或“这个产品线最近 8 周的 TACOS 趋势如何”。

  • 结合自有业务数据分析：例如把产品成本、毛利率、库存压力或目标 ACOS 提供给 AI，让它结合 Xnurta 的广告数据判断哪些广告活动需要调整。

  • 复用固定分析流程：例如把广告周报、月报、商品诊断、广告结构分析等常用任务沉淀为 Skill，减少每次重新描述分析口径的成本。

  • 追溯人工与 AI 操作记录：例如查看某个广告活动近期预算、竞价、投放或托管组相关的操作变更。

  • 管理 AI 托管组（需要写权限）——在 AI 助手里创建、编辑、删除托管组，调整目标 ACOS、托管目标、AI 状态、行动空间，以及托管组下广告活动的绑定关系。

  • 编辑广告(需要写权限)——直接在 AI 助手里改预算、调竞价、开关广告活动、加词 / 加否定词、投放商品。

  • 创建 SP 广告活动（需要写权限）：创建包含广告组、推广商品、投放、否定投放、Placement 设置和可选 Audience bid adjustment 的 SP 广告活动。

3. 您可以查询和管理什么

Xnurta MCP 当前支持三类数据查询、AI 托管组管理、广告实体编辑和 SP 广告活动创建。

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）

  • 添加或移除托管组下的广告活动

3.5 广告实体编辑（需要写权限）

  • 修改广告活动的日预算、状态与竞价策略;

  • 增删关键词、投放、推广商品、否定关键词与否定商品投放;

  • 批量调整竞价等

  • 对支持的广告活动类型编辑 Placement bid adjustment 和 Audience bid adjustment。

3.6 SP 广告活动创建（需要写权限）

  • 创建包含广告组和推广商品的 SP 广告活动。

  • 配置自动投放、关键词投放或商品投放，以及否定投放、Placement 设置和可选 Audience bid adjustment。

4. 使用前准备

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

  • 已开通 Xnurta 平台账号，并拥有需要查询的店铺或广告账户权限。

  • 拥有一个支持 MCP 的 AI 助手，例如 Claude、ChatGPT Codex、WorkBuddy、Cherry Studio、Coze 等。

5. 如何配置 Xnurta MCP

  1. 选择授权方式并连接 MCP——推荐使用 OAuth，也保留 MCP Token 方式。

  2. 安装 Skills 并验证——确认 AI 能正确调用工具并读取授权范围。

  3. 开始使用——用自然语言查询、分析和执行已授权的操作。

选择授权方式并连接 MCP

请根据您的 AI 客户端选择配置路径。Xnurta MCP 支持 OAuth 和 MCP Token 两种授权方式。

  1. 支持自动配置的 AI 客户端：让客户端自动配置 Xnurta MCP，再在浏览器中完成 OAuth 授权。

  2. Claude Cowork、Desktop 和网页版：添加 Custom Connector，再在浏览器中完成 OAuth 授权。

  3. MCP Token：在 Xnurta 创建 Token，并手动添加到支持该方式的 AI 客户端。

您可以在 Xnurta 的 MCP Token 管理页面管理手动创建的 MCP Token。

方式 A：由 AI 客户端自动配置并使用 OAuth 授权

适用于 Claude Code、Codex 等可以根据提示词自动配置 MCP Server 的 AI 客户端。您无需创建、复制或保管 MCP Token。

步骤 1：让 AI 客户端配置 Xnurta MCP 并安装 Skills

  • 将以下提示词发送给 AI 客户端：

请阅读以下 GitHub 仓库，并按说明配置 Xnurta MCP 和安装 Skills：
https://github.com/Xnurta/Xnurta-MCP

步骤 2：在浏览器中完成授权

  • 客户端提示登录或授权时，打开授权页面，登录 Xnurta，确认本次连接。

  • 授权完成后返回 AI 客户端。

步骤 3：确认 Xnurta Skills 已安装

AI 客户端通常会在配置 MCP 时安装 Skills。如果 MCP 已连接但 Skills 未安装，请发送以下提示词：

请阅读以下 GitHub 仓库，并按说明安装 Xnurta Skills：
https://github.com/Xnurta/Xnurta-MCP

方式 B：通过 Custom Connector 连接 Claude Cowork、Desktop 或网页版

Claude Cowork、Claude Desktop 和 claude.ai 需要通过 Custom Connector 连接，不能使用上方提示词让客户端自动完成配置。这些客户端不使用本地 MCP 配置文件，此流程也不支持 MCP Token。

Free / Pro / Max：您可以自行添加 Connector。

  • 进入 Customize > Connectors > + > Add custom connector。

  • 输入 https://mcp.xnurta.com/mcp，然后点击 Add。

Team / Enterprise：需要由 Owner 或 Primary Owner 先为整个组织添加 Connector，再由每位成员单独连接。

  • Owner：进入 Organization settings > Connectors > Add，将鼠标移到 Custom，选择 Web，输入 https://mcp.xnurta.com/mcp，然后点击 Add。Advanced settings 保持为空，不需要填写 OAuth Client ID 或 Secret。

  • 成员：进入 Customize > Connectors，找到 Xnurta MCP，然后点击 Connect。

在打开的浏览器窗口中登录 Xnurta，检查请求的权限和 Profile，确认授权后返回 Claude。每位成员都使用自己的 Xnurta 账号授权，因此组织级 Connector 不会扩大任何成员的店铺范围或权限。

Connector 和 Skills 是两个独立步骤。添加 Connector 只完成 MCP 授权，不会安装 Skills。请在新对话中让 Claude 根据以下仓库安装或更新 Xnurta Skills：

请阅读以下 GitHub 仓库，并按说明安装或更新 Xnurta Skills：https://github.com/Xnurta/Xnurta-MCP

操作截图：

方式 C：在 Xnurta 创建 MCP Token

仅当 AI 客户端支持手动配置 MCP Token 时使用此方式。Claude Cowork、Claude Desktop 和 claude.ai 请使用方式 B。

步骤 1：登录 Xnurta 并创建 Token

  1. 登录 Xnurta 平台，进入 MCP & Skill 页面。

  2. 点击 新建 Token，按需要选择授权范围并创建 Token。

  3. 复制生成的 Token 并妥善保存。

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

步骤 2：在 AI 助手中配置 MCP（推荐）

打开支持 MCP 的 AI 助手后，将下面这段内容发送给 AI：

请阅读这个 GitHub 仓库，并按里面的说明帮我配置 Xnurta MCP 和安装 Skills：
https://github.com/Xnurta/Xnurta-MCP

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

替代方式：手动配置（高级）

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

MCP 服务地址：

https://mcp.xnurta.com/mcp

请求头：

Authorization: Bearer <您的 Token>

Claude Code CLI 示例：

claude mcp add --transport http sparkx-mcp https://mcp.xnurta.com/mcp --header "Authorization: Bearer <您的 Token>"

ChatGPT Codex 示例：

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

不同 AI 助手的 MCP 配置入口可能不同。如遇到 401，通常表示 Token 错误或权限不足；如遇到超时，请先检查网络连接或客户端的 MCP 配置。

现有用户：重新授权并更新 Skills

现有连接不会自动获得新增的写权限。已经使用 Xnurta MCP 的客户，需要重新授权连接并更新 Skills，才能使用广告实体编辑和 SP 广告活动创建。

  • Claude Cowork / Desktop / Web：进入 Settings 或 Customize > Connectors，断开 Xnurta MCP 后重新连接，登录并批准新增权限。只在原 Connector 上重新登录不会更新权限。

  • Claude Code / ChatGPT Codex 及其他可自动配置的客户端：删除或替换现有 MCP 连接，重新完成 OAuth，并调用 get_user_authorized_context 验证新的权限范围。

  • MCP Token 用户：创建一个包含广告编辑权限的新 Token，验证可用后再停用旧 Token。

已经申请广告活动编辑权限的主账号无需单独申请广告活动创建权限，但仍需重新授权并更新 Skills。

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 结合 Xnurta 数据分析。

以下是我的产品成本和目标毛利率。请结合最近 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 仓库中的说明配置 Xnurta MCP 时，AI 助手会直接帮您安装所需的官方 Skills。配置完成后，您可以让 AI 确认已安装的 Skill 列表。

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

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

或：

帮我把 Xnurta MCP 的官方 Skills 装上。

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

7.3 创建自己的 Skill

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

  • 适用场景：例如周会复盘、目标达成检查、产品线预算检查

  • 需要查询的数据：例如广告活动、ASIN、搜索词、操作日志

  • 分析步骤：例如先看总览，再看异常，再看原因，再给建议

  • 输出格式：例如表格、结论摘要、行动项清单

7.4 AI 托管组管理（需要写权限）

  • “找出店铺 XX 中近 30 天有花费但尚未进入 AI 托管的广告活动，并按 ACOS 接近程度分组。”

  • “根据这些分组创建 AI 托管组，目标 ACOS 设为 6%，暂不启用 AI。”

7.5 广告实体编辑（需要写权限）

  • “将这 3 个 SP 广告活动的日预算提高 10%。”

  • “将这些高 ACOS 关键词的竞价降低 15%。”

  • “将广告活动 XX 的搜索结果顶部 Placement bid adjustment 设为 25%，Audience bid adjustment 设为 10%。”

涉及金额、竞价或归档的操作，AI 助手会先展示受影响的对象及变更前后值，确认后再提交。

7.6 SP 广告活动创建（需要写权限）

  • “为这 5 个 ASIN 创建一个日预算为 30 美元的暂停状态 SP 自动广告活动，提交前展示完整结构。”

  • “创建一个 SP 关键词广告活动，加入这些精准匹配关键词、否定关键词、Placement 设置和 Audience bid adjustment。”

SP 广告活动创建采用原子提交：请求中任何一个广告活动校验失败，全部广告活动都不会创建。如需上线前检查，请创建为暂停状态。当前不支持创建 SB 或 SD 广告活动。

8. 常见问题

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

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

访问范围

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

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

数据处理流程

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

第三方 AI 服务的数据处理

工具返回结果进入 AI 客户端后，将由客户选择的 AI 客户端及其模型服务商继续处理。相关数据是否被存储、保留多久以及是否用于产品改进或模型训练，取决于该服务商的产品版本、合同、隐私政策和账户设置，不由 Xnurta 控制。

企业客户应使用经过内部安全和法务团队批准的 AI 服务及企业账户，并根据自身的数据治理要求配置数据保留、模型改进和数据共享选项。

Token 安全

MCP Token 用于识别用户并校验访问权限，应按照密码或 API Key 的安全级别进行管理。请勿在聊天内容、文档或工单中发送 Token，也不应由多人共享同一个个人 Token。如果 Token 泄露或不再使用，请立即在 Xnurta 中将其禁用或删除。

Q2：配置完成后，为什么 AI 还是查不到数据？

请先让 AI 调用 get_user_authorized_context 验证授权信息。如果无法返回授权店铺或 Profile，请检查 Token 是否正确、是否已过期，以及当前账号是否拥有对应店铺或广告账户权限。

Q3：为什么同一个问题，AI 每次输出的内容不完全一样？

MCP 负责提供可查询的数据，最终分析由 AI 助手完成。不同 AI 助手、不同上下文和不同提问方式，可能导致结论组织方式不同。建议在问题中明确时间范围、对象、指标和输出格式。

Q4：什么时候使用 MCP，什么时候使用 InsightAgent？

如果您希望在 Xnurta 平台内快速查看现成分析结论，建议使用 InsightAgent。InsightAgent 更适合开箱即用的广告诊断、异常分析和平台内复盘。

如果您希望在自己的 AI 助手中查询 Xnurta 数据，或需要结合成本、毛利、库存、目标、内部表格等自有上下文进行分析，建议使用 MCP。MCP 更适合自由追问、跨数据源分析、固定报告生成和个性化工作流。

两者不是替代关系，可以结合使用。InsightAgent 适合在平台内快速获得标准结论，MCP 适合把 Xnurta 数据带到您自己的 AI 工作流中继续分析。

Q5：MCP 和直接在 Xnurta 平台看报表有什么区别？

平台报表适合查看固定看板和标准指标；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 操作、指定用户

操作对象

广告活动、广告组、投放、预算、竞价、托管组

动作类型

创建、更新、启用、暂停、预算调整、出价调整

9.4 托管组写操作能力（需写权限）

用途：通过自然语言创建、编辑、排期、删除托管组，支持单个或批量。

新建 / 编辑（可设置项相同，按编辑页分区）

  • 基础：托管组名称、AI 托管状态、AI 人格

  • 目标：托管目标、目标 ACoS

  • 广告活动：托管组总预算、广告活动名称标记、增删 / 绑定托管组下的广告活动

  • AI 行动空间：支持开 / 关行动空间、支持将行动空间从规则（Rule）改为 AI；不支持将行动空间从 AI 改完 规则（Rule）

  • 排期：添加托管组排期

  • 模板：可模板新建托管组

支持批量（一次多个组）；

删除

  • 删除（归档）整个托管组，不可逆。

仅平台 UI（MCP 不支持写）

  • 品牌 / 非品牌 / 竞品模式

  • 词库相关所有功能

9.5 广告实体写操作能力(需写权限)

用途:通过自然语言批量修改广告本身。

广告活动

  • 修改广告活动状态:开启 / 暂停 / 存档

  • 调整预算(绝对值、增减金额、增减百分比、建议预算)

  • 调整竞价策略:固定竞价、动态竞价-仅降低、动态竞价-提高和降低、规则竞价(仅 SP)

  • 添加推广商品(SP / SD)、添加否定关键词(仅 SP)

  • 广告活动级调整：对支持的广告活动类型编辑 Placement bid adjustment 和 Audience bid adjustment。

推广商品

  • 启停和存档

投放:包括自动投放、关键词、商品投放

  • 新增关键词(关键词、关键词组、主题定向)、新增商品投放(ASIN、分类、表达式)

  • 修改状态和竞价

否定投放:包括否定词、否定商品

  • 新增否定词、否定商品

  • 修改否定词、否定商品状态

  • 复制否定词 / 否定商品到其他广告活动或广告组

执行前会先确认

涉及金额、竞价、存档的操作不会直接执行 —— 助手先返回预览(改哪些对象、从什么值改到什么值),你确认后才提交。

存档不可逆

广告活动、推广商品、关键词、投放、否定项的存档均不可逆,无法通过 MCP 恢复。只想临时停投请用「暂停」。

9.6 SP 广告活动创建（需要写权限）

用途：通过自然语言创建一个或多个 SP 广告活动。

  • 创建包含广告组和推广商品的 SP 广告活动。

  • 配置自动投放、关键词投放或商品投放，以及否定投放、Placement bid adjustment 和可选的 Audience bid adjustment。

  • 提交前检查完整结构。请求采用原子提交：任何一个广告活动校验失败，全部广告活动都不会创建。

当前不支持创建 SB 或 SD 广告活动。广告活动创建后不能删除，只能归档，且归档不可撤销。

这是否解答了您的问题？