tslab-mcp

Un servidor MCP que expone pronósticos de series temporales deterministas como herramientas, para que tu agente sea el motor de razonamiento y cada número provenga de Python ordinario y reproducible.

No se llama a ningún LLM en ningún lugar de este paquete. No se requiere ninguna clave API (a menos que solicites TimeGPT, que llama a la API de Nixtla).

Por qué

Algunas bibliotecas de pronóstico incluyen un agente que lee características, elige un modelo y explica el resultado con un LLM en el bucle. Llamar a uno de esos desde tu propio agente anida un agente dentro de otro agente: dos prompts, dos facturas, dos fuentes de no determinismo y una capa intermedia opaca que hace que la justificación de la selección del modelo no sea auditable.

Por lo tanto, aquí el control está invertido: la biblioteca de pronóstico es la herramienta, y tu agente es el que razona. Lee las características, argumenta a favor de una familia de modelos, valida cruzadamente los candidatos y escribe la justificación en un manifiesto. Cada número en el camino es producido por una llamada a la biblioteca que puedes re-ejecutar sin un LLM en la ruta.

Esa división se traslada a cómo se construye el propio paquete. La instalación base ejecuta once modelos estadísticos — AutoARIMA, AutoETS, Theta, CrostonClassic y amigos — a través de statsforecast: aproximadamente 340 MB, sin PyTorch, y se inicia en segundos. Un extra opcional foundation añade los modelos preentrenados de TimeCopilot — Chronos, Moirai, TimesFM, TiRex, Toto y otros — además de Prophet, para cuando una línea base estadística no es suficiente. Una solicitud que solo nombra modelos estadísticos nunca importa TimeCopilot o torch; una solicitud que nombra incluso un modelo fundacional se ejecuta completamente a través de TimeCopilot, que también incluye los modelos estadísticos. De cualquier manera, tsf_list_models informa qué está realmente instalado antes de que te comprometas con un modelo.

Related MCP server: forecast-mcp

Instalar

Requiere Python 3.10+ (se recomienda 3.13, consulte Versión de Python).

uvx tslab-mcp                     # run without installing
uv tool install tslab-mcp         # or install the CLI

La instalación base ejecuta los once modelos estadísticos a través de statsforecast: aproximadamente 340 MB, sin PyTorch, y se inicia instantáneamente. Para los modelos fundacionales preentrenados — Chronos, Moirai, TimesFM, Toto, TiRex — y Prophet, añade el extra:

uvx --from 'tslab-mcp[foundation]' tslab-mcp

El extra foundation trae TimeCopilot, que a su vez trae torch, transformers y lightning: aproximadamente 2 GB en la primera instalación, y la primera llamada a la herramienta que lo toca tarda ~30 segundos en importar. Ambos son únicos, y ninguno es de pago a menos que solicites un modelo que los necesite.

Desde GitHub

uv y uvx aceptan una URL de git en lugar de un nombre de paquete, lo que instala el main actual sin esperar un lanzamiento:

uvx --from git+https://github.com/pedrobtz/tslab-mcp tslab-mcp
uv tool install git+https://github.com/pedrobtz/tslab-mcp        # or install the CLI

# with the foundation extra
uvx --from 'tslab-mcp[foundation] @ git+https://github.com/pedrobtz/tslab-mcp' tslab-mcp

Fija una referencia para cualquier cosa que no sea una prueba casual — la cabeza de la rama puede moverse debajo de ti de otra manera. Un commit funciona hoy; una etiqueta de versión también funcionará una vez que se haya creado:

uv tool install "git+https://github.com/pedrobtz/tslab-mcp@136824c1cc2a"

Desde un clon

git clone https://github.com/pedrobtz/tslab-mcp
cd tslab-mcp
uv sync                              # base
uv sync --extra foundation           # with the pretrained models
uv run tslab-mcp

Configurar

Añade el servidor a la configuración de tu cliente MCP. El archivo difiere por cliente — a menudo .mcp.json en la raíz del proyecto — pero la entrada en sí tiene la misma forma:

{
  "mcpServers": {
    "tslab": {
      "command": "uvx",
      "args": ["tslab-mcp"],
      "env": {
        "TSLAB_MCP_HOME": "~/.tslab-mcp"
      }
    }
  }
}

TSLAB_MCP_HOME establece dónde se escriben los artefactos; por defecto es ~/.tslab-mcp, y las salidas de ejecución se guardan en <home>/runs.

El transporte es solo stdio, por diseño: se asume que tus datos son sensibles y nunca salen de la máquina. El servidor no realiza solicitudes salientes excepto las descargas de pesos de modelo que el propio TimeCopilot realiza para modelos fundacionales, y las llamadas a la API de Nixtla que TimeGPT realiza si lo solicitas específicamente.

GitHub Copilot

Copilot descubre servidores MCP desde un archivo mcp.json y expone sus herramientas en el modo agente — las herramientas no aparecen en el modo de preguntar o editar.

VS Code. Coloca el servidor en .vscode/mcp.json para compartirlo con el repositorio, o ejecuta MCP: Open User Configuration desde la Paleta de Comandos para mantenerlo en tu propio perfil en todos los espacios de trabajo. Ten en cuenta que la clave es servers, no mcpServers:

{
  "servers": {
    "tslab": {
      "type": "stdio",
      "command": "uvx",
      "args": ["tslab-mcp"],
      "env": {
        "TSLAB_MCP_HOME": "${userHome}/.tslab-mcp"
      }
    }
  }
}

Desde un clon, apúntalo al árbol de trabajo en su lugar:

{
  "servers": {
    "tslab": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "${workspaceFolder}", "tslab-mcp"]
    }
  }
}

Luego: abre Chat, cambia el selector de modo a Agente, y usa el botón Herramientas para confirmar que las ocho herramientas tsf_* están listadas y habilitadas. MCP: List Servers muestra el estado del servidor y sus registros, que es donde se explica un inicio fallido. Copilot limita cuántas herramientas pueden estar activas a la vez, por lo que si ejecutas varios servidores MCP, es posible que debas deseleccionar algunos para que quepan las ocho.

Visual Studio. Misma forma JSON, en .mcp.json en la raíz de la solución (o %USERPROFILE%\.mcp.json para todas las soluciones), luego habilita las herramientas desde el selector de herramientas del modo agente de Copilot Chat.

JetBrains, Eclipse y Xcode. Abre el selector de herramientas del modo agente de Copilot Chat, elige Edit MCP configuration y añade la misma entrada servers al mcp.json que se abre.

Copilot coding agent (el agente en la nube en github.com) es una mala opción para este servidor: ejecuta tus servidores MCP dentro de un entorno efímero de GitHub Actions, lo que significa pagar la instalación de ~2 GB de TimeCopilot en cada ejecución, y no tiene acceso a archivos de datos locales. Úsalo desde tu editor en su lugar.

Herramientas

Todo excepto las dos herramientas tsf_export_* está marcado como solo lectura; nada aquí elimina, por lo que limpiar ~/.tslab-mcp/runs es tu responsabilidad, no la del agente.

Iniciar una sesión

Las herramientas no imponen un orden, por lo que el prompt inicial es lo que convierte ocho funciones invocables en un análisis. Algo como esto funciona bien:

Usa las herramientas de tslab para pronosticar la serie en /Users/me/data/deposits.csv, 12 meses adelante.

Trabaja en este orden y muestra tu razonamiento en cada paso:

1. Carga el archivo y dime lo que encontraste — cuántas series, qué frecuencia, si hay huecos o valores faltantes.

2. Describe las características, y di qué familias de modelos sugieren, y por qué.

3. Verifica qué modelos están realmente instalados antes de proponer ninguno.

4. Valida cruzadamente tu lista corta contra una línea base SeasonalNaive en 4 ventanas. Solo modelos estadísticos por ahora.

5. Pronostica con el ganador, con intervalos del 80% y 95%.

6. Exporta un manifiesto de ejecución y un informe HTML, y pon la justificación de la selección del modelo en la nota: qué elegiste, qué mostró la tabla de métricas y qué rechazaste.

Resume los resultados y dame las rutas parquet — no pegues marcos completos en el chat.

Cuatro cosas en ese prompt están haciendo trabajo real:

• Una ruta absoluta. Las rutas relativas se resuelven contra el directorio de trabajo del servidor, que tu cliente MCP elige y generalmente no puedes predecir.

• Un horizonte que coincide con la decisión. h impulsa tanto el pronóstico como cuánto historial consume cada ventana de CV; 12 pasos mensuales es un año de planificación, no un valor predeterminado arbitrario.

• "Solo modelos estadísticos por ahora." Sin esto, un agente puede recurrir a un modelo fundacional y pasar varios minutos descargando pesos para responder una pregunta que AutoETS habría resuelto en segundos. Levanta la restricción una vez que los modelos baratos hayan establecido un piso.

• Pedir la justificación en la nota del manifiesto. La transcripción del chat es desechable; el manifiesto es la parte que alguien puede re-ejecutar y auditar. Si el razonamiento solo existe en la conversación, está efectivamente perdido.

Aperturas más cortas, cuando sabes lo que quieres:

Carga /Users/me/data/sales.parquet y describe las características. No pronostiques todavía — quiero ver con qué estamos tratando primero.

Compara SeasonalNaive, AutoETS y AutoARIMA en el manejador deposits cargado, en 6 ventanas con h=12, luego dime si algo supera la línea base lo suficiente como para que valga la pena la complejidad adicional.

Las llamadas solo estadísticas responden en segundos. La primera llamada que nombra un modelo fundacional tarda ~30 segundos en importar TimeCopilot antes de hacer cualquier otra cosa — esa pausa es esperada, no un bloqueo, y solo ocurre si el extra foundation está instalado y una solicitud realmente recurre a uno.

Una sesión de trabajo

Comienza desde un CSV en formato largo de Nixtla:

unique_id,ds,y
branch_01,2018-01-01,1043.2
branch_01,2018-02-01,1102.7
...

1. Cargarlo. El panel permanece en el proceso del servidor; el manejador es todo lo que lleva la sesión.

{"handle": "deposits", "n_series": 12, "n_obs": 864, "freq": "MS",
 "start": "2018-01-01T00:00:00", "end": "2023-12-01T00:00:00",
 "obs_per_series": {"min": 72, "median": 72, "max": 72},
 "n_missing_y": 0, "sha256": "9f2c…"}

2. Describirlo. Estos son los números sobre los que razonas.

| id        | n  | mean   | cv    | %zero | trend | seasonal | acf1(diff) |
|-----------|----|--------|-------|-------|-------|----------|------------|
| branch_01 | 72 | 1180.4 | 0.112 | 0.0   | 0.83  | 0.62     | -0.31      |

Una alta fuerza estacional y una tendencia clara abogan por AutoETS y AutoARIMA sobre una línea base ingenua; un alto %zero habría abogado por ADIDA o CrostonClassic en su lugar.

seasonal es una fuerza STL — el componente estacional medido contra lo que queda una vez que se elimina la tendencia — por lo que una serie creciente aún informa su estacionalidad honestamente. Lleva un piso de ruido de aproximadamente 0.3–0.5: las puntuaciones en esa banda significan "sin evidencia", no "levemente estacional".

3. Verificar qué está instalado con tsf_list_models, para que nunca propongas un modelo que esta máquina no pueda ejecutar.

4. Validar cruzadamente los candidatos — incluyendo siempre SeasonalNaive, ya que un modelo que no puede superarlo no vale la pena implementarlo:

{"kind": "cross_validation", "models": ["SeasonalNaive", "AutoETS", "AutoARIMA"],
 "h": 12, "n_windows": 4, "seasonality_used_for_mase": 12,
 "metrics": {"mase": {"SeasonalNaive": 1.0, "AutoETS": 0.71, "AutoARIMA": 0.68}},
 "ranking": {"mase": ["AutoARIMA", "AutoETS", "SeasonalNaive"]},
 "artifact": "~/.tslab-mcp/runs/cv_deposits_3f1a9c02.parquet"}

5. Pronosticar con el ganador. El marco completo va a parquet; la respuesta lleva la ruta, las columnas y una vista previa corta.

6. Exportar la ejecución y el informe. Escribe por qué, en la nota — es la única parte de tu razonamiento que sobrevive a la conversación:

{"manifest": "~/.tslab-mcp/runs/manifest_deposits_77b0e415.json", "n_runs": 3,
 "kinds": ["cross_validation", "forecast"]}

El manifiesto contiene la ruta de origen y el hash, la frecuencia, cada llamada con sus argumentos y rutas de artefactos, las versiones fijadas de lo que sea que esté realmente instalado — statsforecast, pandas y Python siempre; TimeCopilot y torch también si el extra foundation está incluido — y tu nota. Es suficiente para reproducir los números con el servidor detenido.

tsf_export_report convierte ese mismo manifiesto en algo que una persona lee — características, tablas de métricas ordenadas de mejor a peor, pronósticos, anomalías y el entorno, en el orden en que ocurrieron:

{"report": "~/.tslab-mcp/runs/report_deposits_5c31d0a7.html",
 "format": "html", "n_steps": 3,
 "steps": ["features", "cross_validation", "forecast"]}

El informe es una función pura del manifiesto: no lee parquet ni llama a ningún modelo, por lo que tsf_export_report con manifest_path re-renderiza una ejecución de hace meses sin nada cargado. El HTML incrusta su propio CSS y no referencia ningún script, hoja de estilo o fuente externa, por lo que aún se abre correctamente sin conexión.

Diseño

Cuatro invariantes, y las razones por las que existen:

Manejadores, no dataframes. Un marco de validación cruzada tiene n_series × h × n_windows × n_models filas. Serializarlo como resultado de una herramienta agota el contexto de la sesión en la primera llamada y empeora cada turno posterior. Las herramientas toman un manejador y devuelven resúmenes, agregados y rutas de archivos; cada ruta masiva está limitada e informa lo que omitió, para que la sesión sepa que debe leer el parquet en lugar de volver a preguntar.

El trabajo bloqueante nunca toca el bucle de eventos. Validar cruzadamente varios modelos sobre un panel grande son minutos de CPU. Cada cuerpo de herramienta es una clausura síncrona enviada a través de anyio.to_thread.run_sync, por lo que el transporte stdio sigue respondiendo y el cliente no abandona el servidor a mitad de la ejecución.

El entorno se descubre, no se asume. Los modelos se importan de forma perezosa y se sondean, nunca se asume que están presentes. tsf_list_models informa lo que realmente se resolvió aquí, por lo que pedir Chronos sin el extra devuelve un mensaje nombrando el extra en lugar de un traceback diez minutos después de iniciada una ejecución.

El backend se elige según lo que pidas: una solicitud cuyos modelos son todos estadísticos se ejecuta a través de statsforecast, y solo una solicitud que necesita un modelo preentrenado recurre a TimeCopilot. Por lo tanto, las ejecuciones estadísticas nunca importan torch, y el servidor se inicia al instante de cualquier manera.

statsforecast se deja deliberadamente en su n_jobs=1 predeterminado. Su modo paralelo genera procesos trabajadores que reimportan el módulo de entrada, lo que dentro de un servidor MCP genera contención y un riesgo en stdout en lugar de velocidad.

El manifiesto es el artefacto de registro. La prosa en la conversación es comentario. El manifiesto es lo que alguien reejecuta en seis meses, y lo que un revisor lee para ver qué modelos se compararon y sobre qué base.

Versión de Python

TimeCopilot condiciona varios modelos a la versión del intérprete, y en Python < 3.13 fija tabpfn-time-series, lo que limita pandas por debajo de 2.2.

3.13 es el objetivo recomendado. En cualquier caso, tsf_list_models informa lo que realmente se resolvió, con la razón de todo lo que no se resolvió.

Desarrollo

uv sync --all-groups
uv run pytest                  # fast suite
uv run pytest -m slow          # exercises TimeCopilot; slower, no weight downloads
uv run ruff check src tests
uv run mypy

Inspecciona la superficie de las herramientas con el MCP Inspector:

npx @modelcontextprotocol/inspector uv run tslab-mcp

Licencia

MIT