内容
# shopify-forecast-mcp
> ⚠️ **v0.1.0 Alpha** — 早期发布版本。API 接口可能会在 v0.2 版本之前发生变化。欢迎反馈：[开启一个问题](https://github.com/mcostigliola321/shopify-forecast-mcp/issues)。
连接 Google 的 TimesFM 2.5 时间序列基础模型到您的 Shopify 商店的商户原生 MCP 服务器 - 让您的 AI 助手能够根据您的订单历史记录提供真实的预测。
无需仪表盘，无需导出，无需每家商店的单独训练。与 Claude Desktop、Claude Code、Cursor 和任何 MCP 兼容的 AI 客户端配合使用。
***
## 为什么
Shopify 有四个官方 MCP 服务器，分别面向买家或开发者。但没有一个服务器是为商户运营而设计的：预测、需求规划、促销分析、异常检测。
现有的第三方工具要么使用弱模型（移动平均、Prophet），要么将洞察锁定在封闭的 SaaS 仪表盘中。这个工具：
- 运行 **TimesFM 2.5** （谷歌的 2 亿参数基础模型）- GIFT-Eval 零售基准测试的最新成果
- 直接从 **Shopify Admin GraphQL** 拉取数据，支持批量操作、退款感知标准化、多币种和基于成本的速率限制
- 返回 **markdown 表格，带有置信区间**，在 MCP 客户端中原生渲染
- 作为一个单独的 `uvx` 命令发布 - 零手动 Python 设置
- **MIT 许可，永久免费**
***
## 快速开始
三个步骤，在 5 分钟内获得一个可用的预测：
### 1. 安装 `uv` （一次）
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex
```
### 2. 获取 Shopify Admin API 访问令牌
按照 [docs/SETUP.md](docs/SETUP.md) 中的说明，创建一个自定义应用，启用所需的范围（`read_orders`、`read_all_orders`、`read_products`、`read_inventory`），并生成一个访问令牌。
### 3. 添加到 Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）或 `%APPDATA%\Claude\claude_desktop_config.json` （Windows），并添加：
```json
{
"mcpServers": {
"shopify-forecast": {
"command": "uvx",
"args": ["shopify-forecast-mcp"],
"env": {
"SHOPIFY_FORECAST_SHOP": "mystore.myshopify.com",
"SHOPIFY_FORECAST_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}
```
重启 Claude Desktop，然后询问：**"下个月的情况如何？"**
首次运行下载 TimesFM 2.5 权重（~400MB，一次性）。后续预测时间 <10 秒。
> **更喜欢在终端使用？** 您可以在连接 Claude Desktop 之前，通过直接运行 `uvx shopify-forecast-mcp` 验证您的设置 - 它在标准输入/输出上启动 MCP 服务器，并在没有客户端连接时使用 Ctrl-C 干净地退出。或者使用 CLI：`uvx --from shopify-forecast-mcp shopify-forecast revenue --horizon 7`。
> **Alpha 预发布版本：** 如果安装 v0.1.0-rc1，请使用 `"args": ["--prerelease=allow", "shopify-forecast-mcp@0.1.0rc1"]` 代替。
另请参阅：[docs/SETUP.md](docs/SETUP.md) 以获取 Claude Code + 通用 MCP 客户端设置、Docker 安装和多商店配置。
***
## 示例
在设置完成后，将以下内容放入您的 AI 客户端：
**收入预测** — *"下个月的情况如何？"*
返回未来 30 天的每日粒度收入预测，带有 80% 置信区间（q10-q90）。
**需求 + 补货提醒** — *"哪些 SKU 需要在接下来的 2 周内补货？"*
返回具有预测需求与当前库存的前 N 个 SKU，标记库存风险。
**促销分析** — *"黑色星期五的表现与去年相比如何？"*
返回两个时间窗口的收入增长、订单增长、平均订单价值变化、折扣深度和促销后余波估计。
**情景规划** — *"比较 3 个 12 月的促销方案：10% 折扣、20% 折扣 + 免费运费和买一送一。"*
返回 3 个差异化预测，一个 markdown 回应，包含每个方案的收入、单位和利润影响。
***
## 工具
七种 MCP 工具，完整参考请参见 [docs/TOOLS.md](docs/TOOLS.md)：
| 工具 | 用途 |
|------|---------|
| [`forecast_revenue`](docs/TOOLS.md#forecast-revenue) | 带有置信区间的商店级收入预测 |
| [`forecast_demand`](docs/TOOLS.md#forecast-demand) | 产品/集合/SKU 需求 + 补货提醒 |
| [`analyze_promotion`](docs/TOOLS.md#analyze-promotion) | 过去的促销与基线 - 增长、平均订单价值、余波 |
| [`detect_anomalies`](docs/TOOLS.md#detect-anomalies) | 标记超出预测分位数区间的日期 |
| [`compare_periods`](docs/TOOLS.md#compare-periods) | 年/年或月/月比较 |
| [`compare_scenarios`](docs/TOOLS.md#compare-scenarios) | 2-4 个场景的假设预测 |
| [`get_seasonality`](docs/TOOLS.md#get-seasonality) | 解释学习的季节性模式 |
***
## 架构
两层设计：一个纯 Python **核心库** （Shopify 客户端、时间序列整形、TimesFM 预测器、分析、协变量）由一个 **薄 MCP 服务器** 和一个 **匹配 CLI** 包装。核心库可以在没有 MCP 运行时导入和测试。
双后端 Shopify 访问：**DirectBackend** （httpx + 访问令牌，在 Docker 中使用和设置 `SHOPIFY_FORECAST_ACCESS_TOKEN` 时使用）或 **CliBackend** （`shopify store execute` - 浏览器 OAuth，无需令牌，主機专用）。
完整的图表 + 设计决策在 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 中。
***
## 配置
最低要求的环境变量：
| 变量 | 用途 |
|----------|---------|
| `SHOPIFY_FORECAST_SHOP` | 您的商店域名（例如 `mystore.myshopify.com`） |
| `SHOPIFY_FORECAST_ACCESS_TOKEN` | 管理 API 访问令牌（来自自定义应用） |
请参阅 [docs/SETUP.md](docs/SETUP.md) 以获取完整环境变量表、多商店配置、Docker 环境变量传递和可选调优旋钮。
***
## CLI
一个独立的 `shopify-forecast` CLI 包装相同的核心库，无需 MCP 运行时 - 可用于脚本、cron 和 CI：
```bash
uvx --from shopify-forecast-mcp shopify-forecast revenue --horizon 30
uvx --from shopify-forecast-mcp shopify-forecast demand --group-by product --top-n 10
uvx --from shopify-forecast-mcp shopify-forecast promo --start 2025-11-24 --end 2025-11-30
uvx --from shopify-forecast-mcp shopify-forecast compare --period-a 2024-11:2024-12 --period-b 2025-11:2025-12
```
在任何动词上添加 `--json` 以获取机器可读的输出。请参阅 [docs/SETUP.md#cli-usage](docs/SETUP.md#cli-usage) 以获取完整的 CLI 参考。
***
## Docker
在没有安装 Python 的情况下运行 MCP 服务器（或任何 CLI 动词）：
```bash
docker run --rm -i \
-e SHOPIFY_FORECAST_SHOP=mystore.myshopify.com \
-e SHOPIFY_FORECAST_ACCESS_TOKEN=shpat_xxx \
ghcr.io/mcostigliola321/shopify-forecast-mcp:latest
```
两种镜像变体：
- **`:latest`** - 首次调用时延迟模型下载（较小的镜像，~1.5GB）
- **`:bundled`** - TimesFM 权重已包含在内（较大的镜像，~2.5GB，离线可用）
基于浏览器的 OAuth 在容器中不工作；Docker 模式需要访问令牌环境变量。请参阅 [docs/SETUP.md#docker](docs/SETUP.md#docker)。
***
## 路线图
v0.1.0 是覆盖完整 MVP（7 种 MCP 工具 + 4 种 CLI 动词 + 双后端）的第一个公开 alpha 版本。未来：请参见 [.planning/ROADMAP.md](.planning/ROADMAP.md)。
***
## 贡献
欢迎在 [GitHub Issues](https://github.com/mcostigliola321/shopify-forecast-mcp/issues) 上提供反馈和错误报告。对于代码贡献，请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 以获取两层设计，并提前开启一个草稿 PR。
***
## 许可证
[MIT](LICENSE)。TimesFM 2.5 权重为 [Apache 2.0](https://huggingface.co/google/timesfm-2.5-200m-pytorch) （兼容）。
