Forecast time series in CSV files: deterministic skforecast workflows and the script that ran.
MCP Server: io.github.skforecast/skforecast-ai
This MCP server supports forecasting time series provided as CSV files. It focuses on deterministic skforecast workflows and includes the script that was run, tying the forecasting process to the specific execution used.
🛠️ Key Features
Forecast time series in CSV files
Deterministic skforecast workflows
Includes the script that ran
🚀 Use Cases
Forecasting time series data stored in CSV format
Reproducing a specific skforecast-based workflow and its execution context
⚡ Developer Benefits
Clear linkage between the workflow and the executed script
Deterministic processing for consistent forecasting runs
⚠️ Limitations
Scope is limited to time series forecasting via CSV inputs
The forecasting assistant that shows its work. Give skforecast-ai a time series: it profiles the data, chooses the model with deterministic rules, validates it and returns the forecast together with the skforecast script that produced it. Every decision comes from a rule you can read, the same data always gives the same result, and the script runs on its own with plain skforecast. An optional LLM explains every decision; it never makes them.
skforecast-ai forecast of hourly bike sharing users with its 80% interval, and the ask() answer that explains the evaluation metrics
36-hour LightGBM forecast of hourly bike sharing users, with its 80% prediction interval against the held-out hours, and the answer of ask() that explains its metrics. Real skforecast-ai outputs, from the animation on ai.skforecast.org.
Installation
bash
pip install skforecast-ai
The LLM layer is optional. To use it, install the extra ([bedrock] for AWS Bedrock):
Try it without installing anything: Your first forecast runs in Google Colab, from the data to a validated forecast, with no API key.
python
from skforecast_ai import ForecastingAssistant
from skforecast.datasets import load_demo_dataset
# Download demo dataset (monthly)
data = load_demo_dataset(verbose=False)
# Profile the data, plan the model, generate the script and run it,# evaluated on the last 12 months. No LLM needed.
assistant = ForecastingAssistant()
result = assistant.forecast(data=data, target="y", steps=12, test_size=12)
result.predictions.head()
# pred# 2007-07-01 0.851486# 2007-08-01 1.048000# 2007-09-01 0.998147# 2007-10-01 1.147577# 2007-11-01 1.110845
result.metrics
# mean_absolute_error root_mean_squared_error mean_absolute_scaled_error \# 0 0.078442 0.094514 0.802828## mean_absolute_percentage_error# 0 0.088608print(result.code) # the skforecast script that produced this result
That single call chose a ForecasterRecursive with a Ridge estimator, its lags and window features, and ran the script that result.code returns. result.profile and result.plan hold every decision and the rule behind it. Drop test_size to train on all the data and forecast the next 12 months.
Same pipeline from the terminal
bash
# End-to-end forecast
skforecast-ai forecast data.csv --target y --date-column date --steps 12
# Only the standalone script, without running it
skforecast-ai forecast-code data.csv --target y --date-column date --steps 12 --output forecast.py
The CLI covers the whole pipeline, including ask() and the prompts of refine_plan() and create_cv(). See Using the CLI.
Ask why (optional LLM)
python
# pip install "skforecast-ai[llm]"
assistant = ForecastingAssistant(llm="openai:gpt-5.5")
answer = assistant.ask(
"Is the MASE good, and why was this estimator chosen?",
context=result,
)
ask() reads the object you pass and explains it, grounded in the skforecast agent skills. It never changes the result. The dataset is never sent: a result shares only its own predictions and metrics, with a warning. Providers, credentials and local models are covered in Configuring the LLM.
From your coding agent (MCP server)
In Claude Code, install the server and its skill as a plugin:
Then ask in plain language: "Forecast the next 12 months of data/sales.csv and tell me how accurate it is." The agent brings the language model and calls skforecast-ai as tools; every decision still comes from the same deterministic rules, every result comes with the script that produced it, and responses never carry rows of your data. The setups for Cursor, VS Code, Codex and Claude Desktop are in MCP server for coding agents.
A coding agent asked to compare models for the next 12 months of a monthly series calls the skforecast-ai MCP server (profile, plan, create_cv, compare, get_code) and answers with the leaderboard against a seasonal naive baseline and the script of the winner
A real Claude Code session with the server and its skill, from the agent check of skforecast-ai 0.5.0, abridged: the first three calls share a row, and an ellipsis marks every cut in a response or in the answer. The whole session shows every call, every message of the agent and its complete answer.
In VS Code, this button adds the server and asks for the directory with your data (it needs uv):
Features
A deterministic engine
Data profiling: frequency, missing values, exogenous and categorical variables, and the significant lags from the partial autocorrelation.
A plan with a rule for every decision: forecaster and estimator, lags, window and calendar features, prediction intervals, metric and cross-validation.
The code you see is the code that ran: forecast() and backtest() execute the same script that forecast_code() and backtest_code() return. Inspect it, version it or run it with plain skforecast.
Model selection with compare(): every candidate is backtested with the same data and cross-validation, and the ranking is a plain sort of the metric. For a single series, a seasonal naive baseline is ranked alongside them, so you also see whether a model beats the simplest reasonable forecast.
Reproducible: the same input always gives the same profile, plan, script and predictions.
Python or terminal: the CLI runs the same pipeline from a CSV file or URL.
Coding agents: an MCP server gives Claude Code, Cursor and other MCP clients the same pipeline as tools, with a skill that teaches them to use it. Responses never carry rows of your data.
The engine chooses among the forecasters of skforecast: recursive and direct, multi-series and multivariate, statistical (ARIMA) and foundation models.
An optional LLM layer
Explains a forecast, a backtest, a comparison, a plan or a script in plain language with ask(), or answers a general forecasting question.
Refines lags and window features from your domain knowledge with refine_plan(prompt=...).
Translates a deployment scenario into a backtesting strategy with create_cv(prompt=...).
Validated before it runs: every LLM output is checked by a Pydantic model; if it is not valid, you get the deterministic result and a warning.
Any provider through pydantic-ai: OpenAI, Anthropic, Google, Groq, AWS Bedrock, Ollama for local models, or any OpenAI-compatible endpoint.
Methods
All methods work without an LLM except ask(). A prompt is always explicit: nothing is sent to an LLM unless you ask for it.
Method
What it does
LLM
profile()
Inspects the data and recommends a forecaster and an estimator
no
plan()
Builds the plan: lags, window and calendar features, interval, metric
no
refine_plan()
Changes a plan with explicit overrides, or with a prompt
optional
create_cv()
Builds the cross-validation strategy, or translates a prompt into one
optional
forecast(), forecast_code()
Runs the forecast, or returns its script without running it
no
backtest(), backtest_code()
Runs the backtest, or returns its script without running it
no
compare()
Backtests several configurations and ranks them
no
ask()
Explains a profile, plan, script or result, or answers a question
required
How it works
skforecast-ai has two ways in, on the same engine. The fast path goes from data to a forecast or a backtest in one call. The step-by-step path returns each intermediate object (profile, plan, cross-validation) so you can inspect it, change it or refine it with the LLM before running anything. Both branch into forecasting and backtesting, compare() picks the best configuration from measured performance, and ask() explains any object along the way.
skforecast: the forecasting library that runs every forecast of skforecast-ai. Machine learning, statistical and foundation models, backtesting and tuning.
Skforecast Studio: a no-code application to build forecasting models visually, which generates production-ready Python code.
If you use skforecast-ai in a scientific publication, please cite the version you used: each version has its own DOI and ready-made citations on Zenodo. To cite skforecast-ai in general, use the DOI that always resolves to the latest release.
APA:
code
Amat Rodrigo, J., & Escobar Ortiz, J. skforecast-ai [Computer software]. https://doi.org/10.5281/zenodo.21338159
BibTeX:
bibtex
@software{skforecast-ai,
author = {Amat Rodrigo, Joaquin and Escobar Ortiz, Javier},
title = {skforecast-ai},
license = {Apache-2.0},
url = {https://ai.skforecast.org/},
doi = {10.5281/zenodo.21338159}
}
The citation metadata is also in CITATION.cff (GitHub's "Cite this repository" button).
Sponsorship and funding
skforecast-ai is built by the skforecast team. skforecast is free, open-source software supported by the Sovereign Tech Fund and by the organizations that sponsor it. If your company relies on skforecast or skforecast-ai, see Sponsorship and funding for sponsorship tiers, support agreements, feature sponsorship and training.
Trademark: The trademark skforecast is registered with the European Union Intellectual Property Office (EUIPO) under the application number 019109684. Unauthorized use of this trademark, its logo, or any associated visual identity elements is strictly prohibited without the express consent of the owner.