timesfm-mcp

PyPI Docs

MCP server for Google's TimesFM 2.5 — give any AI agent zero-config time-series forecasting.

Plug TimesFM 2.5, Google's 200M-parameter foundation model for time-series, directly into Claude Code, Claude Desktop, Cursor, or any MCP client. The agent calls forecast, gets point predictions + uncertainty bands + a trend/seasonality summary, and writes the explanation itself.

No ML configuration. No data pipelines. One line to run.

Forecast chart: 24-month MRR history with 6-month point forecast and 90% confidence band

Chart generated with the statistical baseline. See "Enable TimesFM 2.5" below to use the full neural model.

Quickstart (30 seconds)

uvx timesfm-mcp        # runs over stdio for local agents

Add to your Claude Desktop / Claude Code / Cursor config:

{
  "mcpServers": {
    "forecast": { "command": "uvx", "args": ["timesfm-mcp"] }
  }
}

Then ask your agent: "Forecast the next 6 months from this revenue data and tell me what to expect."

Enable TimesFM 2.5 (optional)

System requirements: ≥ 16 GB RAM · ~800 MB disk (model weights, downloaded on first use) · PyTorch
Not sure? Skip this — uvx timesfm-mcp already works great on any machine.

pip install "timesfm-mcp[timesfm]"

The TimesFM 2.5 source is bundled inside this package (Apache-2.0, Google LLC) — no separate git clone needed. The server auto-detects it and upgrades automatically; no config change required.

Two backends, zero config

Backend	When active	System requirement	Install
Statistical baseline	Always — default	Any machine	`uvx timesfm-mcp`
TimesFM 2.5 (Google)	When installed	≥ 16 GB RAM + ~800 MB disk	`pip install "timesfm-mcp[timesfm]"`

Start with the baseline. It runs on any machine, installs in seconds, and delivers production-ready forecasts. Upgrade to TimesFM only if you need the neural model's extra accuracy and have the RAM for it.

Tools

Tool	What it does
`forecast`	Forecast a single series with optional uncertainty bands
`list_backends`	Report which engine is active (timesfm / baseline)
`backtest`	Hold out the last N points — compare TimesFM vs baseline MAE/sMAPE

Supported clients

Works with any MCP-compatible agent. Verified configs in Client Setup:

Client	Config
Claude Desktop	`claude_desktop_config.json`
Claude Code	`claude mcp add forecast -- uvx timesfm-mcp`
GitHub Copilot (VS Code)	`.vscode/mcp.json`
Cursor	`~/.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Cline (VS Code)	Cline MCP settings panel
Continue.dev	`~/.continue/config.json`
Zed	`~/.config/zed/settings.json`

Documentation

Full docs in the docs/ folder:

Getting Started — installation and first forecast
Client Setup — config for all 8 supported clients
Tool Reference — full parameter docs
Cookbook — SaaS MRR, e-commerce demand, traffic, cloud spend
How It Works — the math and model

Migrating from forecast-mcp

timesfm-mcp is the renamed continuation of forecast-mcp. Update your install:

pip install timesfm-mcp      # replaces: pip install forecast-mcp
uvx timesfm-mcp              # replaces: uvx forecast-mcp

Update your agent config: change "args": ["forecast-mcp"] → "args": ["timesfm-mcp"].

License

Apache-2.0