Ecommerce MCP Automation

**一个示例 Claude Code + MCP 集成：**将 Shopify 和 Meta Ads 以 MCP 工具的形式暴露，并附带一个报表代理，将两者汇总到一份格式化的每日 P&L + 广告效果电子表格中——无需在两个平台之间手动复制粘贴。

这是根据公开的 Shopify Admin API 和 Meta Marketing API 文档构建的演示——并非在真实业务中运行过的东西。它是一个净室（clean-room）示例：真实的端点、真实的认证、真实的分页、真实的错误处理，全新编写，精确展示这类自动化是如何构建的。它以零凭据在模拟模式下端到端运行（用逼真的 fixture 数据代替实时响应），并且一旦设置真实凭据，就会按集成逐一切换到线上模式——参见如何运行。

Shopify 客户端已针对一个真实的 Shopify Partners 开发商店（沙盒商店，而非生产业务）实际运行过——真实的认证、真实的订单、真实的 API 响应。这一过程发现并修复了两个仅靠 mock fixture 未能覆盖的真实可空性边界情况（参见已知简化）。在本仓库中，Meta Ads 默认针对 mock 传输层运行；客户端代码也以同样的方式编写，一旦设置了 META_ACCESS_TOKEN/META_AD_ACCOUNT_ID，就会切换到线上模式。

它能做什么

• 将 Shopify 订单、收入和 COGS 以 MCP 工具的形式暴露（get_orders、get_daily_pnl）

• 将 Meta Ads 花费、展示次数、购买次数和 ROAS 以 MCP 工具的形式暴露（get_insights、get_daily_ad_performance）

• 运行一个报表代理（daily_report.py），并发拉取两者并生成格式化的 .xlsx——包含 Summary、Orders 和 Ad Performance 工作表

• 附带一个 Claude Code Skill，将整个工作流包装在自然语言触发器（“运行每日报告”）后面

• 包含一份已提交的示例输出，无需运行任何东西即可看到结果

Related MCP server: ads-mcp

示例输出

Summary 标签页的渲染预览——打开实际生成的工作簿即可查看真实文件（包含 Orders 和 Ad Performance 工作表、货币/ROAS 格式以及冻结的表头行）。

架构

flowchart LR
    subgraph Shopify["Shopify Admin API"]
        SO[orders.json]
        SI[inventory_items.json]
    end
    subgraph Meta["Meta Marketing API"]
        MI[act_id/insights]
    end

    SO --> SC[shopify_client.py]
    SI --> SC
    MI --> MC[meta_ads_client.py]

    SC --> SS[shopify_server.py<br/>MCP tools]
    MC --> MS[meta_ads_server.py<br/>MCP tools]

    SC --> DR[daily_report.py]
    MC --> DR
    DR --> SPX[spreadsheet.py]
    SPX --> XLSX[(sample_daily_report.xlsx)]

    Mock[["mock_api.py<br/>(ASGITransport, in-process)"]] -.mock mode.-> SC
    Mock -.mock mode.-> MC

两个 API 客户端（clients/shopify_client.py、clients/meta_ads_client.py）是真正的集成代码——真实的端点 URL、真实的认证头、真实的分页循环、真实的 429 退避机制。在模拟模式和线上模式之间，唯一变化的是 HTTP 传输层（clients/http.py）：

• 线上模式：httpx.AsyncClient 打开到 Shopify / Meta 的真实连接。

• 模拟模式：httpx.AsyncClient 被赋予一个 httpx.ASGITransport，指向进程内的 FastAPI 应用（fixtures/mock_api.py），提供逼真的 fixture 负载。不绑定任何端口，也不运行子进程——但请求仍然会经过真实的 HTTP/ASGI 路由、请求头和 JSON 编码。

这意味着评审者读到的客户端代码，与会在真实商店上运行的代码是同一份——而不是伪装成真实代码的 mock。完整的约定请参见 CLAUDE.md。

如何运行

模拟模式（默认——无需任何凭据）

git clone <this-repo> && cd ecommerce-mcp-automation
python -m venv .venv && source .venv/bin/activate   # or: uv sync && source .venv/bin/activate
pip install -e ".[dev]"

python -m ecommerce_mcp.reporting.daily_report
# -> Wrote examples/sample_daily_report.xlsx

用同样的方式运行测试套件，无需任何设置：

pytest

线上模式

将 .env.example 复制为 .env，填入你已有的凭据——每个集成都会在自身凭据就绪的那一刻独立切换到线上模式，因此你可以在 Meta 仍处于模拟状态时以线上模式运行 Shopify（反之亦然）：

cp .env.example .env
# SHOPIFY_STORE_DOMAIN=your-dev-store.myshopify.com
# SHOPIFY_ACCESS_TOKEN=shpat_...          (Partners dev store -> custom app -> Admin API token)
# META_ACCESS_TOKEN=EAA...                (System User token, ads_read scope)
# META_AD_ACCOUNT_ID=act_1234567890

作为 MCP 服务器（Claude Code / Claude Desktop）

添加到你的 MCP 配置中（Claude Code 使用 .mcp.json，或使用 Claude Desktop 的配置文件）。将 command 直接指向项目的 venv 解释器——MCP 客户端不会加载你的 shell 配置文件，因此单独的 python 命令看不到已激活的 venv：

{
  "mcpServers": {
    "shopify": {
      "command": "/path/to/ecommerce-mcp-automation/.venv/bin/python",
      "args": ["-m", "ecommerce_mcp.mcp_servers.shopify_server"],
      "cwd": "/path/to/ecommerce-mcp-automation"
    },
    "meta-ads": {
      "command": "/path/to/ecommerce-mcp-automation/.venv/bin/python",
      "args": ["-m", "ecommerce_mcp.mcp_servers.meta_ads_server"],
      "cwd": "/path/to/ecommerce-mcp-automation"
    }
  }
}

然后可以问 Claude 类似这样的问题：“今天的 Shopify P&L 是多少？”或“帮我查一下昨天的 Meta 广告表现”——它会直接调用这些工具，默认处于模拟模式。

作为 Skill

skills/daily-report/SKILL.md 包装了报表生成工作流，使 Claude Code 能在自然语言触发器（“运行每日报告”）下运行它，而不需要精确的 CLI 命令。完整报表路径完全不需要上面的 MCP 配置——它直接运行 daily_report.py，以纯 Python 方式调用这些客户端，完全不涉及 MCP。只有在 Skill 的另一条路径中才需要 MCP 配置：回答一次性的单一指标问题（“今天的 ROAS 是多少？”）——通过将 get_daily_pnl / get_daily_ad_performance 作为 MCP 工具调用，而不是运行整个报表。

项目结构

src/ecommerce_mcp/
  clients/         Typed, async API clients (Shopify + Meta), transport-swappable
  mcp_servers/      MCP tool servers wrapping the clients
  reporting/        daily_report.py (orchestration) + spreadsheet.py (openpyxl)
  fixtures/         Realistic mock payloads + the in-process mock API app
skills/daily-report/ Claude Code Skill for the reporting workflow
tests/              pytest suite (all run against mock mode)
examples/           Committed sample .xlsx + README preview image

已知简化

在这里明确记录，而不是隐藏，因为对于这样的示例，精确性比精致更重要：

• COGS 通过真实的两跳查询（变体 → inventory_item_id → 批量获取 inventory_items）使用 Shopify 的 InventoryItem.cost 字段——Shopify 不会在订单行项目上直接暴露成本。在真实商店上，cost 和行项目的 sku 都可能是空的（商家可能从未设置过它们）——这是在对真实开发商店进行实际运行测试时发现的，而非仅凭文档。两者都按零成本 / SKU 缺失处理，而不是报错。

• 已退款订单在 daily_pnl() 中会从收入/COGS/订单数中完全排除。部分退款/退货的核算需要 Refund 资源——这超出本文范围。

• Meta 购买归因使用 actions/action_values 数组中的 purchase 操作类型，并采用广告账户配置的任意归因窗口——该客户端不会覆盖它。

• 报表代理目前会拉取所有可用的订单/洞察，而不是按日期范围过滤；生产环境中的每日 cron 任务会为目标日期传入 created_at_min/time_range。

许可证

MIT——参见 LICENSE。