# shopify-forecast-mcp

> ⚠️ **v0.1.0 Alpha** — Early release. API surface may change before v0.2. Feedback welcome: [open an issue](https://github.com/mcostigliola321/shopify-forecast-mcp/issues).

Merchant-native MCP server that connects Google's TimesFM 2.5 time-series foundation model to your Shopify store — so your AI assistant can answer "what does next month look like?" with a real forecast grounded in your order history.

No dashboards, no exports, no per-store training. Works with Claude Desktop, Claude Code, Cursor, and any MCP-compatible AI client.

***

## Why

Shopify has four official MCP servers, all buyer-facing or developer-facing. None serve merchant operations: forecasting, demand planning, promo analysis, anomaly detection.

Existing third-party tools either use weak models (moving averages, Prophet) or lock insights inside closed SaaS dashboards. This one:

- Runs **TimesFM 2.5** (Google's 200M-param foundation model) — state of the art on the GIFT-Eval retail benchmark
- Pulls directly from **Shopify Admin GraphQL** with bulk operations, refund-aware normalization, multi-currency, and cost-based rate limiting
- Returns **markdown tables with confidence bands** that render natively in your MCP client
- Ships as a single `uvx` command — zero manual Python setup
- Is **MIT licensed, free forever**

***

## Quick start

Three steps to a working forecast in under 5 minutes:

### 1. Install `uv` (once)

```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex
```

### 2. Get a Shopify Admin API access token

Follow [docs/SETUP.md](docs/SETUP.md) to create a custom app, enable the required scopes (`read_orders`, `read_all_orders`, `read_products`, `read_inventory`), and generate an access token.

### 3. Add to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and add:

```json
{
  "mcpServers": {
    "shopify-forecast": {
      "command": "uvx",
      "args": ["shopify-forecast-mcp"],
      "env": {
        "SHOPIFY_FORECAST_SHOP": "mystore.myshopify.com",
        "SHOPIFY_FORECAST_ACCESS_TOKEN": "shpat_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Restart Claude Desktop, then ask: **"What does next month look like?"**

First run downloads TimesFM 2.5 weights (~400MB, one-time). Subsequent forecasts are <10 seconds.

> **Prefer the terminal first?** You can verify your setup before wiring Claude Desktop by running `uvx shopify-forecast-mcp` directly — it launches the MCP server on stdio and will exit cleanly on Ctrl-C when no client is attached. Or exercise the CLI: `uvx --from shopify-forecast-mcp shopify-forecast revenue --horizon 7`.

> **Alpha pre-release:** if installing v0.1.0-rc1, use `"args": ["--prerelease=allow", "shopify-forecast-mcp@0.1.0rc1"]` instead.

See also: [docs/SETUP.md](docs/SETUP.md) for Claude Code + generic MCP client setup, Docker install, and multi-store configuration.

***

## Examples

Drop these into your AI client after setup:

**Revenue forecasting** — *"What does next month look like?"*
Returns a daily-granularity revenue forecast for the next 30 days with an 80% confidence band (q10–q90).

**Demand + reorder alerts** — *"Which SKUs need to be reordered in the next 2 weeks?"*
Returns top-N SKUs with projected demand vs current inventory, flagging stockout risk.

**Promo analysis** — *"How did Black Friday perform vs last year?"*
Returns revenue lift, order lift, AOV change, discount depth, and post-promo hangover estimate for both windows side by side.

**Scenario planning** — *"Compare 3 promo scenarios for December: 10% off, 20% off + free shipping, and BOGO."*
Returns 3 differentiated forecasts in one markdown response with per-scenario revenue, units, and margin implications.

***

## Tools

Seven MCP tools, full reference in [docs/TOOLS.md](docs/TOOLS.md):

| Tool | Purpose |
|------|---------|
| [`forecast_revenue`](docs/TOOLS.md#forecast-revenue) | Store-level revenue forecast with confidence bands |
| [`forecast_demand`](docs/TOOLS.md#forecast-demand) | Product/collection/SKU demand + reorder alerts |
| [`analyze_promotion`](docs/TOOLS.md#analyze-promotion) | Past promo vs baseline — lift, AOV, hangover |
| [`detect_anomalies`](docs/TOOLS.md#detect-anomalies) | Flag days outside forecast quantile bands |
| [`compare_periods`](docs/TOOLS.md#compare-periods) | Year-over-year / month-over-month comparison |
| [`compare_scenarios`](docs/TOOLS.md#compare-scenarios) | What-if forecasting across 2-4 scenarios |
| [`get_seasonality`](docs/TOOLS.md#get-seasonality) | Explain learned seasonal patterns |

***

## Architecture

Two-layer design: a pure-Python **core library** (Shopify client, time-series shaping, TimesFM forecaster, analytics, covariates) wrapped by a **thin MCP server** and a **matching CLI**. Core is importable and testable without the MCP runtime.

Dual-backend Shopify access: **DirectBackend** (httpx + access token, used in Docker and when `SHOPIFY_FORECAST_ACCESS_TOKEN` is set) or **CliBackend** (`shopify store execute` — browser OAuth, no token required, host-only).

Full diagrams + design decisions in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

***

## Configuration

Minimum required env vars:

| Variable | Purpose |
|----------|---------|
| `SHOPIFY_FORECAST_SHOP` | Your store domain (e.g. `mystore.myshopify.com`) |
| `SHOPIFY_FORECAST_ACCESS_TOKEN` | Admin API access token (from custom app) |

See [docs/SETUP.md](docs/SETUP.md) for the full env var table, multi-store config, Docker env passing, and optional tuning knobs.

***

## CLI

A standalone `shopify-forecast` CLI wraps the same core library without the MCP runtime — useful for scripting, cron, and 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
```

Add `--json` to any verb for machine-readable output. See [docs/SETUP.md#cli-usage](docs/SETUP.md#cli-usage) for the full CLI reference.

***

## Docker

Run the MCP server (or any CLI verb) without installing Python:

```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
```

Two image variants:
- **`:latest`** — lazy model download on first call (smaller image, ~1.5GB)
- **`:bundled`** — TimesFM weights baked in (larger image, ~2.5GB, offline-capable)

Browser-based OAuth does NOT work in containers; Docker mode requires the access-token env var. See [docs/SETUP.md#docker](docs/SETUP.md#docker).

***

## Roadmap

v0.1.0 is the first public alpha, covering the full MVP (7 MCP tools + 4 CLI verbs + dual-backend). Future: see [.planning/ROADMAP.md](.planning/ROADMAP.md).

***

## Contributing

Feedback and bug reports welcome at [GitHub Issues](https://github.com/mcostigliola321/shopify-forecast-mcp/issues). For code contributions, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the two-layer design and open a draft PR early.

***

## License

[MIT](LICENSE). TimesFM 2.5 weights are [Apache 2.0](https://huggingface.co/google/timesfm-2.5-200m-pytorch) (compatible).