内容
# timesfm-mcp
基于GPU的本地TimesFM 2.5预测服务器。
该软件包通过`stdio`、`sse`或`streamable-http`将谷歌的TimesFM模型暴露给MCP客户端。它适用于本地或可信网络服务，代理需要零镜头时间序列预测、预测区间、协变量预测、CSV预测和基于区间的异常评分。
## 提供内容
- `guidance`: 面向代理的安全TimesFM预测使用指南。
- `health`: 软件包、CUDA、系统和模型状态报告，附带CUDA矩阵乘法探测。
- `estimate_memory`: 在加载大任务之前进行粗略的数据集内存估计。
- `warmup`: 在实时请求之前惰性加载并编译TimesFM到GPU。
- `forecast_values`: 预测内存中的数值序列。
- `forecast_csv`: 预测本地CSV中的数值列并写入CSV或JSON。
- `forecast_with_covariates_values`: TimesFM 2.5 XReg预测，带有已知的未来协变量。
- `detect_anomalies`: 将未来的实际值与q20/q80和q10/q90预测带进行比较。
- `timesfm://forecasting/guide`: 具有相同操作指南的MCP资源。
- `timesfm_forecasting_guide`: 代理在计划预测前的MCP提示。
模型是一个进程单例。它在第一次`warmup`或预测调用时加载，并保存在内存中，直到MCP服务器进程退出。如果请求更改模型设置，如`max_context`、`max_horizon`、`batch_size`或`infer_is_positive`，服务器将使用新设置重新加载模型。
## 使用场景
使用此服务器进行零镜头单变量时间序列预测：
- 销售、需求、收入、交通、库存和产能规划。
- 传感器读数、生命体征、负载、天气、价格和测量。
- 需要q10到q90预测带的概率预测。
- 已知未来协变量预测，如价格、促销、假期、天气、商店属性、产品系列或地区影响。
- 使用预测区间进行预测与实际的异常审查。
不要将其用于分类、聚类、因果解释、系数分析、一般表格预测或模型微调。微调是一种训练工作流程，故意不通过此推理MCP服务器公开。
## 使用uv进行GPU设置
对于RTX 5090和其他新NVIDIA GPU，在安装此软件包之前，请安装支持GPU架构的PyTorch轮。CUDA 12.8轮是此类机器的推荐起点。
```bash
git clone https://github.com/chokukil/timesfm-mcp.git
cd timesfm-mcp
uv venv .venv-gpu --python 3.10
source .venv-gpu/bin/activate
uv pip install --upgrade --reinstall \
torch torchvision torchaudio \
--index-url https://download.pytorch.org/whl/cu128
uv pip install -e ".[gpu]"
uv pip check
```
`.[gpu]`安装TimesFM torch、XReg和Flax相关组件，包括`einshape`。如果您只需要标准的torch预测而无需XReg/Flax依赖项，请安装`.[torch]`。如果您需要XReg但不需要Flax，请安装`.[xreg]`。
在启动MCP之前验证CUDA：
```bash
uv run --python .venv-gpu/bin/python python - <<'PY'
import torch
print(torch.__version__)
print(torch.cuda.is_available())
print(torch.cuda.get_device_name(0))
x = torch.randn((512, 512), device="cuda")
y = x @ x
torch.cuda.synchronize()
print("cuda matmul ok")
PY
```
## 启动服务器
以保守的批量大小启动。 除非您故意隐藏GPU，否则不要设置`CUDA_VISIBLE_DEVICES=`。
```bash
export TIMESFM_BATCH_SIZE=64
export PYTHONNOUSERSITE=1
timesfm-mcp --transport sse --host 0.0.0.0 --port 8765
```
SSE端点将是：
```text
http://<host>:8765/sse
```
适用于本地stdio客户端：
```bash
timesfm-mcp --transport stdio
```
适用于可流式HTTP：
```bash
timesfm-mcp --transport streamable-http --host 0.0.0.0 --port 8765
```
## 环境变量
| 变量 | 默认值 | 含义 |
| --- | --- | --- |
| `TIMESFM_MODEL_ID` | `google/timesfm-2.5-200m-pytorch` | Hugging Face模型ID或本地模型路径。 |
| `TIMESFM_MAX_CONTEXT` | `1024` | 编译模型使用的最大上下文点数。 |
| `TIMESFM_MAX_HORIZON` | `256` | 最大预测范围。 |
| `TIMESFM_BATCH_SIZE` | `64` | TimesFM `per_core_batch_size`；仅在内存稳定后增加。 |
| `TIMESFM_NORMALIZE_INPUTS` | `true` | 在预测之前标准化每个输入序列。 |
| `TIMESFM_CONTINUOUS_QUANTILE_HEAD` | `true` | 使用连续分位数头以获得更好的预测带。 |
| `TIMESFM_FORCE_FLIP_INVARIANCE` | `true` | 强制符号对称性。 |
| `TIMESFM_INFER_IS_POSITIVE` | `true` | 将仅为正的序列限制为非负输出。 |
| `TIMESFM_FIX_QUANTILE_CROSSING` | `true` | 强制单调分位数。 |
| `TIMESFM_RETURN_BACKCAST` | `false` | 内部默认值；XReg请求强制设为`true`。 |
| `TIMESFM_TORCH_COMPILE` | `false` | 加载模型时启用PyTorch编译。 |
当指标可能低于零时，请按需将`infer_is_positive`设置为`false`，或将`TIMESFM_INFER_IS_POSITIVE`设置为`false`：回报、残差、PnL、温度异常、z分数或有符号增量。
## 代理工作流程
1. 读取`guidance`或`timesfm://forecasting/guide`资源。
2. 调用`health`。如果`cuda_probe.passed`为`false`，请在加载前修复PyTorch/CUDA。
3. 为大型工作负载调用`estimate_memory`。
4. 如果延迟很重要，则调用`warmup`一次。
5. 使用与输入形状匹配的预测工具。
6. 谨慎解释分位数：索引0为平均值，然后是q10到q90。
`q10`和`q90`形成中心80％的预测区间。`q20`和`q80`形成中心60％的区间。
## 工具示例
### 预测值
```json
{
"inputs": [[10, 12, 11, 13, 15, 16, 18, 19, 21, 22, 24, 25, 27, 28, 30, 31, 33, 34, 36, 37, 39, 40, 42, 43, 45, 46, 48, 49, 51, 52, 54, 55]],
"horizon": 7,
"names": ["sales"],
"infer_is_positive": true
}
```
### 带有协变量的预测
动态协变量的长度必须为每个序列的`len(input_series) + horizon`。尾部值是已知的未来协变量。
```json
{
"inputs": [[100, 101, 103, 105, 104, 106, 108, 109, 111, 113, 112, 114, 116, 118, 119, 120, 122, 124, 123, 125, 127, 129, 130, 132, 133, 135, 137, 138, 140, 141, 143, 145]],
"horizon": 4,
"dynamic_numerical_covariates": {
"price": [[9.9, 9.9, 9.8, 9.8, 9.7, 9.7, 9.7, 9.6, 9.6, 9.6, 9.5, 9.5, 9.5, 9.5, 9.4, 9.4, 9.4, 9.3, 9.3, 9.3, 9.2, 9.2, 9.2, 9.1, 9.1, 9.1, 9.0, 9.0, 9.0, 8.9, 8.9, 8.9, 8.8, 8.8, 8.8, 8.8]]
},
"static_categorical_covariates": {
"region": ["seoul"]
},
"xreg_mode": "xreg + timesfm"
}
```
### 检测异常
```json
{
"inputs": [[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32]],
"actuals": [[33, 60]],
"horizon": 2,
"names": ["metric"]
}
```
严重性规则：
- `normal`：实际值在q20至q80之间。
- `warning`：实际值在q20至q80之外，但在q10至q90之内。
- `critical`：实际值在q10至q90之外。
## 安全
SSE和可流式HTTP传输本身不添加身份验证。绑定到`127.0.0.1`仅限本地使用。绑定到`0.0.0.0`仅限在可信网络或通过您自己的身份验证、防火墙或反向代理。
## 开发
```bash
uv pip install -e ".[gpu,dev]"
pytest -q
ruff check .
```
## 许可证
Apache-2.0。本仓库封装了TimesFM，并依赖上游`timesfm` Python软件包和模型权重。
