# forecast-mcp

An MCP server (Model Context Protocol) that exposes a three-tier demand
forecasting and replenishment pipeline as tools. Any MCP client can call it:
Cursor, Claude Desktop, Claude Code, Google Antigravity, Windsurf, and
anything else that speaks MCP.
Each series is classified with Syntetos–Boylan statistics (ADI and CV²) and
routed to one model:

| Pattern | Typical series | Model |
|---|---|---|
| Cold-start | <14 days of history | Mean of observed demand |
| Intermittent / lumpy | Sparse, mostly-zero demand | TSB (`statsforecast`) |
| Regular / erratic | Continuous daily demand | AutoETS (`statsforecast`) |

Cutoffs: ADI = 1.32, CV² = 0.49 (`classification.py`).

## Tools

| Tool | Purpose |
|---|---|
| `list_skus` | IDs in the loaded dataset |
| `classify_demand_pattern` | Pattern + model tier |
| `forecast_series` | Horizon forecast after routing |
| `evaluate_forecast` | Holdout backtest (MASE) |
| `recommend_replenishment` | Reorder point and order quantity |
| `explain_forecast` | Routing rationale |

## Data

The server generates a synthetic 25-SKU panel in memory on startup (regular,
erratic, intermittent, lumpy, and cold-start). No external dataset or API key
is required.

To use your own history, pass a CSV with `unique_id`, `ds` (date), `y` (units):

```bash
python -m forecast_mcp.server --data examples/sample_demand.csv
# or
export FORECAST_MCP_DATA=/path/to/demand.csv
```

## Setup

```bash
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -e ".[ui]"
```

## Run

```bash
python -m forecast_mcp.server
python -m forecast_mcp.server --transport http --port 8765
python -m forecast_mcp.ui
```

HTTP health: `http://127.0.0.1:8765/health`  
MCP endpoint: `http://127.0.0.1:8765/mcp`  
UI: `http://127.0.0.1:7860`

Point the MCP `command` at this project's `.venv/bin/python`.

## Tests

```bash
pip install pytest
pytest tests/ -v
```

## Client config

stdio (default) and Streamable HTTP are both supported. Example configs are
in `examples/mcp/`, plus `.cursor/mcp.json` and `.agents/mcp_config.json`.

```json
{
  "mcpServers": {
    "forecast-mcp": {
      "command": "/absolute/path/to/forecast-mcp/.venv/bin/python",
      "args": ["-m", "forecast_mcp.server"]
    }
  }
}
```

HTTP:

```json
{
  "mcpServers": {
    "forecast-mcp": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}
```

Some clients use `serverUrl` instead of `url`.

## Extensions

- Cold-start: replace the mean fallback in `forecast_cold_start()` with a
  zero-shot foundation model (e.g. Chronos-Bolt).
- Extra candidates per tier: score with MASE in `evaluation.py`.
- Storage: swap `DataStore` for ClickHouse, Postgres, or DuckDB.
- Regular tier with exogenous features: `mlforecast` + LightGBM.

## Layout

```
forecast-mcp/
├── src/forecast_mcp/
│   ├── server.py
│   ├── data.py
│   ├── classification.py
│   ├── forecasting.py
│   ├── evaluation.py
│   ├── replenishment.py
│   └── ui.py
├── scripts/
├── examples/
├── tests/
├── requirements.txt
└── pyproject.toml
```

Rohan Singh · [github.com/RohanSingh02](https://github.com/RohanSingh02)