An MCP (Model Context Protocol) server for time series forecasting powered by Nixtla's TimeGPT foundation model.
Add to your Claude Code settings (~/.claude.json) or MCP client:
{
"mcpServers": {
"forecasting": {
"type": "http",
"url": "https://your-deployment.vercel.app/api/mcp"
}
}
}npm install
npm run cliAdd to Claude Code for local usage:
{
"mcpServers": {
"forecasting": {
"type": "stdio",
"command": "npx",
"args": ["tsx", "cli.ts"],
"cwd": "/path/to/forecasting-mcp"
}
}
}npm install
npx vercel- Zero-shot forecasting - No training required, works out of the box
- Multi-series support - Forecast multiple time series in a single request
- Exogenous variables - Include external factors that influence your forecast
- Prediction intervals - Quantify uncertainty with configurable confidence levels
- Feature contributions - Understand which factors drive your predictions
Generate time series forecasts from CSV data.
| Parameter | Type | Required | Description |
|---|---|---|---|
csv_content |
string | No* | CSV content with time series data |
csv_url |
string | No* | URL to fetch CSV data from (S3, HTTP). Takes priority over csv_content |
h |
number | Yes | Forecast horizon (number of periods) |
freq |
string | Yes | Data frequency (see below) |
model |
string | No | Model selection (default: timegpt-1) |
level |
number[] | No | Prediction interval percentages, e.g., [80, 95] |
clean_ex_first |
boolean | No | Preprocess exogenous signals (default: true) |
feature_contributions |
boolean | No | Return feature importance scores |
X_future_content |
string | No | CSV content with future exogenous values |
X_future_url |
string | No | URL to fetch future exogenous CSV data from |
save_to_bucket |
boolean | No | Save output to Vercel Blob and return download URL (default: true) |
*Either csv_content or csv_url must be provided.
| Code | Frequency |
|---|---|
H |
Hourly |
D |
Daily |
W |
Weekly |
M |
Monthly (end) |
MS |
Monthly (start) |
Y |
Yearly |
| Model | Use Case |
|---|---|
timegpt-1 |
Default. Best for forecasts within one seasonal period |
timegpt-1-long-horizon |
Extended forecasts beyond one seasonal period |
The CSV content must contain these columns:
| Column | Required | Description |
|---|---|---|
unique_id |
Yes | Series identifier |
ds |
Yes | Timestamp (ISO 8601 format) |
y |
Yes | Target values to forecast |
| additional | No | Exogenous features |
Example:
unique_id,ds,y,temperature,is_holiday
store_NYC,2024-01-01,1520,32,1
store_NYC,2024-01-02,1340,35,0
store_NYC,2024-01-03,1425,33,0
store_LA,2024-01-01,2100,68,1
store_LA,2024-01-02,1890,71,0
store_LA,2024-01-03,1950,69,0The forecast is returned as CSV:
unique_id,ds,forecast,lo_90,hi_90
store_NYC,2024-01-04,1467.3,1389.2,1545.4
store_NYC,2024-01-05,1502.8,1411.6,1594.0
store_LA,2024-01-04,1978.5,1856.3,2100.7
store_LA,2024-01-05,2015.2,1879.8,2150.6Forecast the next 7 days with daily frequency using this data:
unique_id,ds,y
sales,2024-01-01,100
sales,2024-01-02,120
...
Generate a 12-month forecast with 80% and 95% prediction intervals for monthly sales data
Forecast energy demand for 24 hours including temperature as an exogenous variable
Forecast the next 30 days using data from https://my-bucket.s3.amazonaws.com/sales.csv with daily frequency
By default, forecast output is saved to Vercel Blob and a download URL is returned.
To get raw CSV content instead, set save_to_bucket: false.
| Variable | Required | Description |
|---|---|---|
NIXTLA_API_KEY |
No* | Nixtla API key (has default) |
BLOB_READ_WRITE_TOKEN |
No | Required for save_to_blob feature |
# Install dependencies
npm install
# Run development server (HTTP mode)
npm run dev
# Run CLI mode (stdio)
npm run cli| Error | Cause | Solution |
|---|---|---|
CSV file is empty |
No data provided | Ensure CSV content is not empty |
Missing required columns |
CSV missing unique_id, ds, or y |
Ensure CSV has required columns |
Invalid frequency |
Unsupported frequency code | Use one of: H, D, W, M, MS, Y |
Exogenous mismatch |
Future exogenous columns don't match input | Ensure same exogenous columns in both CSVs |
Limits depend on your Nixtla API plan. See Nixtla pricing for details.
- Next.js - React framework
- Vercel - Hosting platform
- mcp-handler - MCP SSE server adapter
- @modelcontextprotocol/sdk - MCP stdio server
- Nixtla TimeGPT - Foundation model for time series
MIT