Amazon Data Core

把 Amazon 订单、库存、广告和结算数据同步到本地，并先验证数据是否完整、及时、可追溯，再交给你选择的 AI 或分析工具使用。

Amazon Data Core 是本地数据引擎和只读 MCP Server，不是广告优化 Agent，也不是聊天界面。它负责提供可信的经营事实，不替用户或模型做主观经营决策。

本项目由 LGURT 维护，官方源代码仓库仅为 YYYBO-H/amazon-data-core。 Amazon Data Core 是独立的开源项目，不是 Amazon 官方产品，也不代表 Amazon。

**交给本地 Agent：**发送完整仓库地址 https://github.com/YYYBO-H/amazon-data-core，再说“帮我在本机安装并引导我完成配置”。 仓库根目录的 AGENTS.md 会告诉 Agent 下一步，不需要复制一大段提示词。

适合谁

• 没有研发团队，希望让现有 Agent 使用自己真实店铺数据的 Amazon 卖家和运营人员；

• 需要统一数据口径、质量检查和本地存储的服务商与技术团队；

• 希望更换 AI 工具时，不必重新同步和解释全部数据的用户。

Related MCP server: databricks-mcp

当前支持

FBM/MFN 库存、Sponsored Brands/Display、Targeting、Ads Unified Reporting 和 Finances v2024 实时流水尚未支持。完整边界见项目范围和路线图。

交给 Agent 安装

前提是 Agent 能读取 GitHub 仓库并在你的电脑上执行命令。用户只需给出上面的完整仓库地址并提出安装要求；Agent 应自动读取根目录的 AGENTS.md，再按 AGENT_INSTALL.md 执行，不应要求用户复制安装提示词。

Agent 专用的完整执行契约见 AGENT_INSTALL.md。Agent 需要具备本机命令执行能力，但不需要拥有可交互终端；普通网页聊天产品仍不能代替你安装。

Agent 会先运行一个不读取密钥的环境检查：

python3 scripts/preflight.py

它会用 JSON 返回 Docker、Compose、Python、平台支持情况和唯一的 next_action，便于 Agent 明确告诉用户当前该做什么。

在终端安装

需要 Git、Docker Desktop（含 Docker Compose v2）和用于启动脚本的 Python 3.9 或更高版本。Core 本身在 Docker 中使用 Python 3.11：

git clone https://github.com/YYYBO-H/amazon-data-core.git
cd amazon-data-core
./scripts/onboard.sh

onboard.sh 会安装服务、执行数据库迁移和自检，然后启动独立的后台任务，自动打开一个只监听 127.0.0.1 的临时本机授权页面。页面以“店铺范围 → SP-API → 可选广告”三步引导，并在提交后显示授权验证和首次同步的过渡状态。即使 Agent 的命令会话已经结束，该页面仍可访问。你在页面里亲自填写凭证，提交后后台任务自动继续首次同步。凭证不会经过 Agent 聊天，只写入权限为 0600 且已被 Git 忽略的本机 .env。

目前已验证的入口是 macOS、Linux，以及 Windows 中的 WSL2。原生 Windows PowerShell 安装尚未验证；预检会明确返回 use_wsl2，不会假装已经兼容。

如果系统不能自动打开浏览器，请打开命令输出的 http://127.0.0.1:... 临时地址。只有浏览器也不可用时，才使用终端备用方式：

./scripts/onboard.sh --terminal-config

随时查询后台授权或同步状态：

python3 scripts/onboard_background.py status

只安装空白 Core、暂不连接 Amazon：

./scripts/install.sh

首次连接真实店铺前，你仍需拥有自己组织的 Amazon private SP-API 应用并完成自授权。广告数据还需要单独的 Amazon Ads 应用授权和 Profile ID。开源代码不能绕过 Amazon 审核、OAuth 同意或所需角色，详见 Amazon 授权说明。

如何确认安装完成

完整的新用户流程只有在 python3 scripts/onboard_background.py status 显示 complete 时才算完成；后台日志中同时会有 First sync passed。如果某个数据集失败，状态会是 sync_failed，日志会列出失败项，不会把“部分成功”描述成“全部完成”。

空白 Core 可以用以下命令验证：

curl --fail http://localhost:8080/health
docker compose exec -T core amazon-data-core doctor
docker compose exec -T core python scripts/verify_mcp.py
docker compose exec -T core amazon-data-core status

本地服务启动后提供：

• 同步状态页：http://localhost:8080（每 3 秒刷新分数据集的真实分页数、记录数、错误和恢复命令）

• API 文档：http://localhost:8080/docs

• 同步状态 JSON：http://localhost:8080/v1/sync-status

• 数据健康：http://localhost:8080/v1/data-health

• 只读 MCP Server：amazon-data-core mcp

状态页只有在必选数据集已经到达且质量检查通过时，才会显示“当前数据可以交给 Agent 分析”。Amazon Ads 没有配置时会明确显示为可选跳过，不会阻塞订单、FBA 库存和结算。

数据为什么可以核验

每次同步都会保留数据来源、店铺、站点、业务日期、抓取时间、源更新时间、原始引用和处理版本，并明确记录：

• 同步是否完整，源记录数与标准化、去重数量是否相符；

• 数据是否过期、仍在归因窗口内或后来被 Amazon 修正；

• 迟到数据是否比当前版本更新，是否可以切换为当前事实；

• 检查是 passed、failed、skipped 还是 error；

• 当前问题是否仍然开放，以及后续成功是否已经关闭旧问题。

缺失数据不会被解释为零销售、零广告或零库存。经营数据摘要类 MCP 查询会同时返回相应的数据覆盖范围和 safe_to_analyze 判断。

文档

• 什么时候选择 Amazon Data Core

• 常见问题

• 项目范围与非目标

• 连接器、同步命令与数据口径

• Amazon 授权说明

• Agent 安装契约

• 版本记录

• 路线图

• 安全政策

• FBA 库存验证

• 广告 Campaign 验证

• 广告明细验证

• 结算验证

通用 Skill 位于 skills/amazon-data-core/SKILL.md，可以通过 amazon-data-core install-skill --host generic 安装。不同 Agent 的 MCP 配置入口可能不同；项目提供标准 MCP stdio 服务，但不声称所有产品都使用同一个配置文件或都具备本机执行权限。

开发验证

python3 -m pytest

维护方：LGURT · 官方仓库：YYYBO-H/amazon-data-core · 许可证：Apache-2.0