# TimestralMCP

A small, generic MCP server for zero-shot time-series forecasting with [Timestral](https://github.com/mistralai/timestral) (Mistral AI), running locally on CPU.

It is split in two parts so that the model stays agnostic of whatever feeds it:

```
MCP client (Claude, ...)
   │  passes a numeric series
   ▼
timestral_mcp.py        thin MCP (stdio), starts the service on demand
   │  HTTP, 127.0.0.1 only
   ▼
timestral_service.py    FastAPI + Timestral, knows nothing about your data
```

Any other MCP (a database, a CRM, a spreadsheet) can provide the history; this server only turns a series into quantile forecasts.

## Install

Requires Python 3.10+.

```bash
git clone https://github.com/firo/TimestralMCP.git
cd TimestralMCP
./setup.sh
```

`setup.sh` creates `.venv` and installs `requirements.txt` (the MCP SDK is pinned to `<2`).

The first forecast downloads the model weights from Hugging Face (about 837 MB for `Timestral-209M`). Set `HF_HUB_OFFLINE=1` afterwards to run fully offline.

## Configure your MCP client

```json
"timestral": {
  "command": "/absolute/path/to/TimestralMCP/.venv/bin/python",
  "args": ["/absolute/path/to/TimestralMCP/timestral_mcp.py"]
}
```

The MCP starts the local service by itself on first use (log in `service.log`). To run the service manually:

```bash
.venv/bin/uvicorn timestral_service:app --host 127.0.0.1 --port 8765
```

## Tools

- `timestral_forecast(series, horizon, quantile_levels?, model?)`: one series (list of numbers) or a batch (list of lists), in chronological order and with a constant step. `null` means missing. Returns the median and the requested quantiles for each step. Default quantiles are 0.1, 0.5 and 0.9; valid levels are 0.01, 0.05, 0.1 ... 0.95, 0.99.
- `timestral_health()`: checks the service and starts it if it is down.

Environment variables: `TIMESTRAL_MODEL` (default `mistralai/Timestral-209M`), `TIMESTRAL_URL` (default `http://127.0.0.1:8765`), `TIMESTRAL_START_TIMEOUT` (seconds).

Only univariate series are exposed for now. Quantiles of different steps cannot be summed to get the quantiles of a total.

## Licenses

The code in this repository is released under Apache 2.0 (see `LICENSE`).

The Timestral code is Apache 2.0, but the **model weights are distributed separately by Mistral AI under their own license** (see the model card on Hugging Face). Read it before using the weights, especially for commercial use. This repository does not include or redistribute any weights.