tslab-mcp

一个MCP服务器，将确定性时间序列预测暴露为工具，让你的智能体成为推理引擎，而每个数字都来自普通、可复现的Python。

此包中不调用任何LLM。无需API密钥（除非你请求TimeGPT，它会调用Nixtla API）。

为什么

一些预测库自带一个智能体，它读取特征、选择模型，并通过LLM循环解释结果。从你自己的智能体中调用这样的库，相当于在智能体内部嵌套了另一个智能体——两次提示、两次计费、两个非确定性来源，以及一个不透明的中间层，使得模型选择理由无法审计。

因此，这里的控制权被反转了：预测库是工具，你的智能体才是进行推理的一方。它读取特征、论证模型家族、交叉验证候选模型，并将推理过程写入清单。过程中的每个数字都由库调用产生，你可以在没有LLM参与的情况下重新运行。

这种分离也体现在包本身的构建方式上。基础安装通过statsforecast运行十一个统计模型——AutoARIMA、AutoETS、Theta、CrostonClassic等：约340 MB，无需PyTorch，启动只需几秒。可选的foundation扩展增加了TimeCopilot的预训练模型——Chronos、Moirai、TimesFM、TiRex、Toto等——以及Prophet，用于统计基线不够用的情况。只指定统计模型的请求永远不会导入TimeCopilot或torch；即使指定一个基础模型的请求也会完全通过TimeCopilot运行，而TimeCopilot也包含了统计模型。无论哪种情况，tsf_list_models都会在你提交模型之前报告实际安装的内容。

Related MCP server: forecast-mcp

安装

需要Python 3.10+（推荐3.13，参见Python版本）。

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

基础安装通过statsforecast运行十一个统计模型：约340 MB，无需PyTorch，启动即完成。对于预训练的基础模型——Chronos、Moirai、TimesFM、Toto、TiRex——以及Prophet，添加扩展：

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

foundation扩展会拉取TimeCopilot，它带来了torch、transformers和lightning：首次安装约2 GB，第一次调用相关工具时大约需要30秒导入。两者都是一次性的，除非你请求需要它们的模型，否则无需付费。

从GitHub安装

uv和uvx都接受git URL代替包名，这会安装当前的main分支，无需等待发布：

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

对于非临时测试，请固定一个引用——否则分支头可能会在你不知情的情况下移动。使用commit可以正常工作；一旦有版本标签，使用版本标签也可以：

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

从本地检出安装

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

配置

将服务器添加到你的MCP客户端配置中。不同客户端的配置文件不同——通常是项目根目录下的.mcp.json——但条目本身的格式相同：

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

TSLAB_MCP_HOME设置工件写入位置；默认为~/.tslab-mcp，运行输出存放在<home>/runs下。

传输方式仅限stdio，这是有意为之：假设你的数据是敏感的，永远不会离开机器。服务器不会发出出站请求，除了TimeCopilot为基础模型执行的模型权重下载，以及如果你特别请求TimeGPT时它调用的Nixtla API。

GitHub Copilot

Copilot从mcp.json文件中发现MCP服务器，并在agent模式下暴露其工具——这些工具不会出现在ask或edit模式中。

VS Code。 将服务器放在.vscode/mcp.json中以与仓库共享，或从命令面板运行MCP: Open User Configuration以将其保留在你自己的配置文件中，跨所有工作区使用。注意键是servers，而不是mcpServers：

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

从本地检出安装时，将其指向工作树：

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

然后：打开Chat，将模式选择器切换到Agent，使用Tools按钮确认八个tsf_*工具已列出并启用。MCP: List Servers显示服务器的状态及其日志，这是查看启动失败原因的地方。Copilot限制了同时激活的工具数量，因此如果你运行多个MCP服务器，可能需要取消选择一些以容纳全部八个工具。

Visual Studio。 相同的JSON格式，放在解决方案根目录下的.mcp.json中（或所有解决方案的%USERPROFILE%\.mcp.json），然后从Copilot Chat agent模式的工具选择器中启用工具。

JetBrains、Eclipse和Xcode。 打开Copilot Chat agent模式的工具选择器，选择Edit MCP configuration，将相同的servers条目添加到打开的mcp.json中。

Copilot coding agent（github.com上的云智能体）不适合此服务器：它在临时的GitHub Actions环境中运行你的MCP服务器，这意味着每次运行都要支付约2 GB的TimeCopilot安装费用，而且它无法访问本地数据文件。请从你的编辑器中使用它。

工具

除了两个tsf_export_*工具外，所有工具都标记为只读；这里不会删除任何内容，因此清理~/.tslab-mcp/runs是你的责任，而不是智能体的。

开始一个会话

这些工具不强制顺序，因此开场提示是将八个可调用函数转化为分析的关键。类似这样的提示效果很好：

使用tslab工具预测/Users/me/data/deposits.csv中的序列，预测12个月。

按此顺序工作，并在每一步展示你的推理：

1. 加载文件并告诉我你发现了什么——有多少序列、什么频率、是否有任何间隙或缺失值。

2. 描述特征，并说明它们支持哪些模型家族，以及原因。

3. 在提出任何模型之前，检查哪些模型实际已安装。

4. 将你的候选列表与SeasonalNaive基线在4个窗口上进行交叉验证。目前仅使用统计模型。

5. 使用胜出模型进行预测，带80%和95%的区间。

6. 导出运行清单和HTML报告，并将模型选择理由放在注释中：你选择了什么、指标表显示了什么、以及你拒绝了什么。

总结结果并给我parquet路径——不要将整个数据框粘贴到聊天中。

该提示中有四个要点在发挥实际作用：

• 绝对路径。 相对路径相对于服务器的工作目录解析，而工作目录由你的MCP客户端选择，你通常无法预测。

• 与决策匹配的预测步长。 h驱动预测以及每个CV窗口消耗的历史数据量；12个月步长是一年的规划，而不是任意默认值。

• "目前仅使用统计模型。" 没有这个限制，智能体可能会选择基础模型，花费几分钟下载权重来回答AutoETS几秒钟就能解决的问题。在廉价模型设定了基线后再解除限制。

• 要求将推理过程放在清单注释中。 聊天记录是可丢弃的；清单才是可以重新运行和审计的部分。如果推理只存在于对话中，它实际上就丢失了。

当你明确需求时，更简短的开场提示：

加载/Users/me/data/sales.parquet并描述特征。先不要预测——我想先看看我们面对的是什么。

比较SeasonalNaive、AutoETS和AutoARIMA在已加载的deposits句柄上，在h=12时跨6个窗口，然后告诉我是否有任何模型比基线好到值得增加额外复杂度。

仅统计模型的调用在几秒内完成。第一个指定基础模型的调用在开始任何其他操作之前需要大约30秒导入TimeCopilot——这个暂停是预期的，不是挂起，并且只有在安装了foundation扩展且请求实际使用了基础模型时才会发生。

一个完整的会话示例

从Nixtla长格式的CSV开始：

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

1. 加载它。 数据面板保留在服务器进程中；句柄是会话携带的所有内容。

{"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. 描述它。 这些是你进行推理的数字。

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

高季节性强度和明显的趋势支持使用AutoETS和AutoARIMA而不是朴素基线；高%zero则会支持使用ADIDA或CrostonClassic。

seasonal是STL强度——在去除趋势后剩余的季节性成分——因此增长中的序列仍然诚实地报告其季节性。它带有大约0.3–0.5的噪声基底：该范围内的分数意味着"无证据"，而不是"轻微季节性"。

3. 检查已安装的内容使用tsf_list_models，这样你永远不会提出这台机器无法运行的模型。

4. 交叉验证候选模型——始终包括SeasonalNaive，因为无法击败它的模型不值得部署：

{"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. 使用胜出模型进行预测。 完整数据框写入parquet；响应包含路径、列和简短预览。

6. 导出运行和报告。 在注释中写下原因——这是你的推理中唯一比对话存活时间更长的部分：

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

清单包含源路径和哈希、频率、每次调用及其参数和工件路径、实际安装的任何内容的固定版本——始终包括statsforecast、pandas和Python；如果安装了foundation扩展，还包括TimeCopilot和torch——以及你的注释。它足以在服务器停止的情况下重现数字。

tsf_export_report将相同的清单转化为人类可读的内容——特征、按最佳优先排序的指标表、预测、异常和环境，按发生顺序排列：

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

报告是清单的纯函数：它不读取parquet也不调用模型，因此使用manifest_path的tsf_export_report可以在没有任何加载内容的情况下重新渲染几个月前的运行。HTML嵌入自己的CSS，不引用任何外部脚本、样式表或字体，因此离线时也能正常打开。

设计

四个不变性，以及它们存在的原因：

处理句柄，而非数据框。 单次交叉验证框架会生成 n_series × h × n_windows × n_models 行数据。若将其序列化为工具结果，首次调用就会耗尽会话上下文，导致后续每轮交互效果变差。工具应返回句柄、摘要、聚合结果和文件路径；所有批量路径都有上限并会报告遗漏内容，以便会话主动读取 Parquet 文件而非重复请求。

阻塞操作绝不触碰事件循环。 对大型面板数据集进行多模型交叉验证可能需要数分钟 CPU 耗时。每个工具体均为通过 anyio.to_thread.run_sync 派发的同步闭包，确保 stdio 传输持续响应，客户端不会在服务器运行中途断开连接。

环境信息通过探查而非假定获取。 模型采用惰性加载和探测机制，从不假定其存在。tsf_list_models 会报告当前环境实际解析到的内容；若请求 Chronos 但缺少额外依赖，则会返回提示安装依赖包的消息，而非在运行十分钟后抛出回溯错误。

后端根据请求内容自动选择：仅含统计模型的请求使用 statsforecast 运行，只有需要预训练模型的请求才会调用 TimeCopilot。因此统计模型运行永不导入 torch，服务器在任何情况下都能瞬间启动。

statsforecast 特意保持默认 n_jobs=1 设置。其并行模式会衍生工作进程并重新导入入口模块，这在 MCP 服务器内部不仅会引发资源竞争和标准输出风险，且无法带来速度提升。

清单是记录性产物。 对话中的说明性文字仅为补充说明。清单才是六个月后他人重新运行时的依据，也是评审者查看哪些模型在何种基准下被比较的依据。

Python 版本要求

TimeCopilot 根据解释器版本限制部分模型。在 Python < 3.13 时，它会固定使用 tabpfn-time-series，这将 pandas 限制在 2.2 以下。

推荐使用 3.13。无论如何，tsf_list_models 都会报告实际解析到的内容，并说明未解析项的原因。

开发

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

使用 MCP Inspector 检查工具接口：

npx @modelcontextprotocol/inspector uv run tslab-mcp

许可证

MIT