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):

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

Setup

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

Run

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

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.

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

HTTP:

{
  "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