DataDive

@datadive-tools/mcp

一个 MCP 服务，可让 Claude（或任何兼容 MCP 的客户端）使用你现有的 API 密钥查询 DataDive 的细分市场、关键词、竞争对手和 Rank Radar 数据。

在你的计算机上通过 stdio 本地运行。除作为请求发送至 api.datadive.tools 的 x-api-key 标头外，你的 API 密钥不会离开你的计算机。

你可以询问的内容

• “列出我在 marketplace com 中的 DataDive 细分市场。”
• “细分市场 z515cGOFg3 的主关键词列表是什么？”
• “细分市场 X 中的头部竞争对手有哪些？他们的销售额是多少？”
• “细分市场 X 的排名权重是多少？我可以从哪里改进？”
• “显示我的 Rank Radar。”
• “绘制 2024-03-01 至 2024-04-01 期间 Rank Radar Y 的自然排名趋势图。”
• “在美国 marketplace 中，对 ASIN B08N5WRWNW 运行一次细分市场分析，并添加 5 个竞争对手。”
• “用今天的数据刷新细分市场 X，竞争对手保持不变。”
• “重新分析细分市场 X，添加 12 个竞争对手，但保留 B08N5WRWNW。”
• “分析完成了吗？”
• “在细分市场 X 中，为 ASIN B08N5WRWNW 启动一个追踪 10 个关键词的 Rank Radar。”
• “连接了哪些 Amazon 卖家账户？”
• “在我的目录中搜索美国市场中处于启用状态的 ‘widget’ 产品。”
• “上周我的商品信息有哪些价格或内容变更？”

1. 获取 DataDive API 密钥

1. 在 https://2.datadive.tools 登录。
2. 前往 Settings → API Key（/api-key）。
3. 点击 Generate API Key。复制该值，稍后将其粘贴到下面的 MCP 客户端配置中。

需要 Billing Manager 或 Owner 角色，以及 Standard plan 或更高版本。如果看不到此页面，请联系组织管理员。

2. 将其添加到 MCP 客户端

Claude Desktop

编辑配置文件：

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

在 mcpServers 下添加 datadive 条目：

{
  "mcpServers": {
    "datadive": {
      "command": "npx",
      "args": ["-y", "@datadive-tools/mcp"],
      "env": {
        "DATADIVE_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

重启 Claude Desktop。你应该会在工具菜单中看到 datadive。

Claude Code

claude mcp add datadive -- npx -y @datadive-tools/mcp
# Then add the env var via:
#   claude mcp add datadive --env DATADIVE_API_KEY=YOUR_API_KEY -- npx -y @datadive-tools/mcp

或者，在项目中的 .mcp.json 或全局文件 ~/.claude/mcp.json 中编辑配置，使用与上面相同的 JSON 结构。

Cursor

前往 Settings → MCP → Add new MCP server，粘贴相同的 JSON 结构：

{
  "datadive": {
    "command": "npx",
    "args": ["-y", "@datadive-tools/mcp"],
    "env": { "DATADIVE_API_KEY": "YOUR_API_KEY" }
  }
}

3. 验证

向 Claude 询问：“列出我的 DataDive 细分市场。”

你应该会看到对 list_niches 的工具调用，以及包含细分市场和分页元数据的 JSON 响应。如果没有，请参阅下方的故障排除部分。

可用工具

工具	描述
list_niches	分页列出你的细分市场。发现步骤——返回下方细分市场范围工具所需的 nicheId。
list_niches	分页列出你的细分市场。发现步骤——返回下方细分市场范围工具所需的 nicheId。可按 searchText、searchAsin、spaces 或 labels 筛选；每个细分市场都会列出其 spaces 和 labels 的 ID。
list_spaces	以树形结构列出你的 Spaces（id、name、path、children）。已连接的成员只能看到自己有权限访问的 Spaces。ID 可用于 add_niche_spaces 和 spaces 筛选。
list_labels	以树形结构列出你的标签。ID 可用于 add_niche_labels 和 labels 筛选。
list_fast_keywords	分页列出你组织的 Fast Keywords 任务（fastKeywordsId、ASIN、状态、关键词数量、搜索量）。可按 search 或 marketplace 筛选。
get_fast_keywords	获取一项 Fast Keywords 结果：产品、关键词词根和前 10 名竞争对手。轮询，直到 status 为 success。
get_fast_keywords_keywords	获取已完成的 Fast Keywords 任务中的关键词：搜索量、自然排名和赞助排名，按搜索量从高到低排列。支持分页（最多 100 条）。
run_fast_keywords	消耗 1 个 dive token。 仅凭产品 ASIN 查找其关键词。异步执行——轮询 get_fast_keywords。会先预览费用，并要求 confirm: true。
refresh_fast_keywords	消耗 1 个 dive token。 重新运行 Fast Keywords 结果；每 24 小时最多运行一次。要求 confirm: true。
get_niche_keywords	获取细分市场的主关键词列表：搜索量、相关性、竞争对手 ASIN 排名。
get_niche_roots	获取细分市场的关键词词根——具有高影响力的词语及其出现频率和总体搜索量。
get_niche_competitors	获取竞争对手 ASIN、标题、BSR、类别和细分市场统计数据（销量、收入、评分、机会评分）。
get_ranking_juice	获取 DataDive 专有的每个竞争对手的排名权重指标（当前列表与优化后列表）。
list_rank_radars	分页列出排名雷达。可按 nicheId、searchText、spaces、labels（通过细分市场匹配）或 status 筛选（默认 ACTIVE，也可选 PAUSED、ARCHIVED、ALL）。
get_rank_radar_data	获取指定 startDate/endDate 范围内排名雷达的历史关键词排名（最多 90 天）。默认返回所有活跃关键词；传入 currentPage/pageSize（最多 100 条）可逐页读取。
get_rank_radar_sqp_data	获取每个排名雷达关键词的 Amazon 搜索查询表现：搜索量、展示次数、点击次数、加购次数、购买次数——市场总量与此 ASIN 家族的数据。日期范围和分页方式与 get_rank_radar_data 相同。
get_rank_radar_ppc_data	获取每个排名雷达关键词的 Sponsored Products 指标：赞助排名、支出、销售额、ACOS、CPC、匹配类型；可选按广告活动细分。日期范围和分页方式与 get_rank_radar_data 相同。
create_niche_dive	消耗 dive token。 从种子 ASIN 开始新的细分市场研究。异步执行——返回 diveId，可通过 get_dive_status 轮询。传入 fastKeywordsRequestId（来自 run_fast_keywords）可将其关联到 Fast Keywords 任务。要求 confirm: true。
create_niche_dive_from_competitors_list	消耗 dive token。 从你自己的 2–200 个竞争对手 ASIN 列表开始细分市场研究，不进行自动发现。异步执行——返回 diveId，可通过 get_dive_status 轮询。要求 confirm: true。
redive_niche	消耗 dive token。 使用当前数据刷新现有细分市场——可使用相同的竞争对手，也可发现一组新的竞争对手。异步执行——返回 diveId，可通过 get_dive_status 轮询。要求 confirm: true。
add_niche_keywords	将关键词添加到细分市场的主关键词列表（每次调用 1–100 个）。最近 24 小时内完成 dive 的细分市场可免费添加。对于较早的细分市场，此操作会重新 dive 并消耗 dive token——随后会先要求 confirm: true。
remove_niche_keywords	从细分市场的主关键词列表中移除关键词：手动添加的关键词会被删除，来自 Outliers/Residue 的关键词会返回原处，通过 dive 发现的关键词则会保留。免费。
list_keyword_exclusions	列出细分市场从主关键词列表中隐藏的关键词：精确条目及其搜索量，以及短语条目及其隐藏的关键词数量和搜索量。
add_keyword_exclusions	从细分市场的主关键词列表中隐藏关键词——可添加 exact（单个关键词）或 phrase（包含该词的所有关键词），每次调用 1–100 个条目。免费；可通过 remove_keyword_exclusions 撤销。
remove_keyword_exclusions	移除精确或短语排除项，使其隐藏的关键词重新显示。免费。
add_niche_spaces / remove_niche_spaces	将细分市场加入 1–100 个 Spaces，或从中移除（spaceIds 来自 list_spaces）。免费，无需 confirm。仅限组织所有者或团队管理员操作；如果你对某个 Space 只有查看权限，则会拒绝操作。任何 ID 未知或无权限都会导致整个调用失败且不作任何更改。
add_niche_labels / remove_niche_labels	对标签执行相同操作（labelIds 来自 list_labels）。仅限组织所有者或团队管理员操作。
get_dive_status	轮询由 create_niche_dive 或 redive_niche 启动的 dive：in_progress、success（包含 nicheId）或 error。
create_rank_radar	消耗 Search Term token。 开始跟踪细分市场中某个 ASIN 的关键词排名。返回 rankRadarId。要求 confirm: true。
add_rank_radar_search_terms	开始跟踪现有排名雷达上的其他关键词。每个新关键词占用一个每日跟踪关键词名额；可通过 pause_rank_radar_search_terms 撤销。
pause_rank_radar_search_terms	暂停排名雷达中的单个关键词，保留其历史记录并释放跟踪名额。使用 get_rank_radar_data 获取关键词 ID。
resume_rank_radar_search_terms	恢复跟踪排名雷达中已暂停的关键词。每个关键词会重新占用一个跟踪名额。
pause_rank_radar	暂停整个排名雷达（API 将此操作称为归档——会列在 status: PAUSED 下，而非 ARCHIVED）。停止跟踪、保留历史记录并释放跟踪名额。可通过 resume_rank_radar 撤销。
resume_rank_radar	重新激活已暂停的排名雷达，并根据剩余配额恢复尽可能多的关键词（优先恢复相关性最高的关键词）。
delete_rank_radar	销毁排名历史记录。 永久删除排名雷达（会列在 status: ARCHIVED 下）并释放其跟踪名额。要求 confirm: true——如果之后可能需要这些数据，请优先使用 pause_rank_radar。
delete_niche	销毁细分市场数据。 删除细分市场及其关键词、竞争对手和 dive 历史记录；已消耗的 dive token 不予退还。细分市场仍被排名雷达使用时无法删除。要求 confirm: true。
generate_listing_copy	消耗一个 AI Copywriter 提示词。 根据细分市场的关键词研究，起草优化后的标题、要点和描述。不会将任何内容发布到 Amazon。异步执行——返回 generationId。要求 confirm: true。
get_listing_copy_generation_status	轮询由 generate_listing_copy 启动的草稿：generating、complete（包含生成的文案）或 failed。轮询免费。
list_seller_profiles	分页列出已连接的 Amazon 卖家账户。发现步骤——返回下方卖家范围工具（以及提醒工具）所需的 sellerId 和 marketplace。
get_seller_catalog	分页列出卖家自己的 ASIN 商品目录。可按 search、brand 和 status 筛选（默认 Active）。
get_seller_listing_changes	分页列出卖家商品信息的价格、内容和图片变更。可按 types、asin、brand、search 和日期范围筛选；可选包含排名/转化率的 correlation。
list_ppc_campaigns	列出卖家账户的 Sponsored Products 广告活动，包含时间段汇总和按广告位细分的数据。可按 asin / parentAsin、state、search 筛选；可按任意指标排序。时间范围最长 90 天（默认 30 天）。
get_asin_inventory_distribution	获取某个 ASIN 的库存指标（库存量、库存可维持天数、低库存状态、LILF 和 LTSF 费用、库龄商品数量）及其各履约中心的可售库存。需要提供来自 list_seller_profiles 或“连接”页面的 sellerId。
list_indexing_issue_alerts	分页列出索引问题提醒——ASIN 不再被其跟踪的关键词收录。可按 sellerId、marketplace、status 或 updatedSince 筛选。
list_blind_spend_alerts	分页列出无效支出提醒——搜索词广告支出较高但销售额很少或没有，并提供每个搜索词的支出/点击次数/CVR。筛选条件与上述相同。
get_quota	获取每项计费功能当前的配额用量和容量，以及下次刷新日期。无需参数。
list_usage	分页列出计费使用日志（token 消耗事件）。可按 type、search（用户）以及 startDate/endDate 筛选。
所有数据的范围均限定为拥有该 API 密钥的组织。大多数工具为只读。会更改数据的工具已在上方标出；无法撤销的工具还需要显式设置 confirm: true——请参阅会更改数据的工具。

会更改数据的工具

有 6 个工具无法撤销，因此需要显式传入 confirm: true 参数。不传入该参数时，工具不会更改任何数据，而是返回一条说明，要求助手先向你确认费用：

• create_niche_dive、redive_niche——消耗细分市场分析令牌（随 numberOfCompetitors 增加）。
• create_rank_radar——消耗搜索词令牌（随 numberOfKeywords 增加）。
• generate_listing_copy——每次调用消耗 1 条 AI 文案助手提示词。
• delete_niche、delete_rank_radar——永久销毁数据。

你可以随时使用 get_quota 查看剩余额度。

create_rank_radar 会先通过这次未经确认的调用向 API 预览创建操作，因此它返回的说明可以提供具体信息，而不仅仅是令牌费用——例如，你请求的产品系列已由另一个 Rank Radar 跟踪，这会导致它被重复计入跟踪搜索词。预览不会创建任何内容，也不会消耗任何资源；警告也不会阻止创建：在同一产品系列上创建两个 Rank Radar，正是跟踪两组不同搜索词并分别统计数据的方式。

其他写入工具——pause_rank_radar、resume_rank_radar 和 3 个 *_rank_radar_search_terms 工具——无需确认。它们只会调整每日跟踪关键词容量；暂停后容量会释放，且每个操作都能通过对应的操作撤销。

add_niche_keywords 仅在会产生消耗时要求设置 confirm: true：对于过去 24 小时内分析过的细分市场，首次调用会免费添加关键词；对于较早分析过的细分市场，调用不会更改任何数据，而是返回此次添加会触发重新分析所需的令牌费用。remove_niche_keywords 和关键词排除工具免费且无需确认。

如要跳过每次调用时的确认（例如在自动化设置中），请在客户端配置中设置 DATADIVE_AUTO_CONFIRM_WRITES=true——之后这 6 个工具都可不带 confirm 运行，包括删除操作。

这 3 类操作均不适合重试——每次调用都会再次消耗令牌，并创建单独的分析、重新分析或 Rank Radar，即使参数完全相同也不例外。如果调用报错或超时，请先查看 get_dive_status / list_niches / list_rank_radars，确认已有内容，再决定是否再次调用。

分析操作是异步的。create_niche_dive 会立即返回 diveId 和预计完成时间；请使用该 diveId 轮询 get_dive_status，直到状态显示为 success。成功响应中会包含新的 nicheId，之后可将其传给 list_niches、get_niche_keywords 和其他细分市场工具。

redive_niche 会刷新已有细分市场，而不是创建新的细分市场，并且会保留相同的 nicheId——因此，基于该细分市场构建的排名雷达和报告会沿用刷新后的数据。它接受一个 mode：

• same_competitors——重新分析该细分市场当前的竞品集。无需提供其他参数；仅用于获取最新的销量、价格和关键词数据。
• discover——重新搜索包含 numberOfCompetitors 个 ASIN 的竞品集。可使用 heroAsin（用于构建竞品集的种子，默认为销量最高的竞品；如果你自己的 ASIN 之一符合条件，则优先选择它）、lockedAsins（无论搜索结果如何都保留）和 excludedAsins（永不选取）来调整结果。

⚠️ 对于 create_niche_dive，marketplace 使用完整的 Amazon 域名后缀（com、co.uk、com.mx、co.jp 等）——例如，英国站点应使用 co.uk，而不是 uk。

配置

环境变量	必填	默认值	说明
DATADIVE_API_KEY	是	—	在 https://2.datadive.tools/api-key 生成
DATADIVE_API_BASE_URL	否	https://api.datadive.tools	用于覆盖暂存环境
DATADIVE_AUTO_CONFIRM_WRITES	否	false	设置为真值后，所有 confirm: true 的工具都可以无需确认直接运行——包括 dive、创建 rank radar、列表文案和两项删除操作。

故障排查

如果工具调用返回错误消息，可能是以下情况之一——每种情况都对应 DataDive API 的特定 HTTP 状态码。

消息开头为……	处理方法
Authentication failed: your DATADIVE_API_KEY is invalid or expired	密钥错误、已删除或已过期。请在 https://2.datadive.tools/api-key 生成新密钥。
Subscription is inactive or paused	请在 https://2.datadive.tools 恢复账单；API 密钥有效，但订阅未激活。
Quota exceeded / … quota exceeded	订阅中该计费功能的配额（Dive 令牌、Rank Radar 跟踪关键词、AI Copywriter 提示词等）已用尽。消息会指出具体功能、用量、下次刷新日期（如有），并链接到可提高配额的订阅概览页面。配额提高前请勿重试。
Forbidden	密钥有效，但无权访问该资源。通常是属于其他组织的细分市场/rank-radar。
Rate limit exceeded	等待几秒后重试。
Bad request	检查参数——消息会回显服务器的验证错误（例如，pageSize must not exceed 50）。
DataDive API error (5xx)	后端暂时出现问题。请重试；如果问题仍然存在，请联系支持团队。
Network error reaching …	你的机器无法连接到 api.datadive.tools——请检查 VPN / 防火墙 / DNS。

如果服务本身无法启动，请查看 MCP 客户端的日志输出：

• DATADIVE_API_KEY environment variable is required — 未将环境变量传递给二进制文件。请确认客户端配置将其放在 env 下（而非 args），并在编辑后重启客户端。

隐私

• MCP 服务在你的机器本地运行。它只是一个轻量封装——每次工具 调用都会从你的机器向 api.datadive.tools 发送一个 HTTPS 请求， 并将你的 API 密钥作为 x-api-key 标头。
• API 密钥仅存储在 MCP 客户端的配置文件中（由你控制）。 它不会发送到其他任何地方。
• 服务本身不会记录日志。DataDive 的标准后端访问日志会记录每次请求的元数据（组织、路由、状态、延迟）， 与直接调用 API 时相同。

开发

npm install
npm run build       # tsup -> dist/index.js (with shebang)
npm test            # vitest run
npm run typecheck   # tsc --noEmit
npm run lint        # eslint

使用 MCP Inspector 对二进制文件进行端到端测试：

DATADIVE_API_KEY=YOUR_API_KEY npx @modelcontextprotocol/inspector dist/index.js

发布

此仓库使用 Changesets：

npx changeset             # add a changeset describing the change (patch/minor/major)
git commit -am "fix: ..."
git push

系统会自动创建一个“Version Packages”PR。合并后会更新版本号、 更新 CHANGELOG.md，并通过 provenance 发布到 npm。

支持

• 问题反馈： https://github.com/Data-Dive-Tools/datadive-mcp/issues
• API 文档： https://developer.datadive.tools/docs#/v1
• DataDive 支持： [email protected]

许可证

MIT — 详见 LICENSE。