tslab-mcp

時系列予測をツールとして公開するMCPサーバーです。予測は決定論的で再現可能なPythonによって行われ、エージェントは推論エンジンとして機能します。

このパッケージ内でLLMが呼び出されることは一切ありません。APIキーも不要です（TimeGPTを使用する場合を除きます。その場合はNixtla APIを呼び出します）。

なぜ

一部の予測ライブラリは、特徴量を読み取り、モデルを選択し、LLMを介して結果を説明するエージェントを搭載しています。そのようなライブラリを自身のエージェントから呼び出すと、エージェントの中にエージェントが入れ子になります。つまり、2つのプロンプト、2つの課金、2つの非決定論的要因、そしてモデル選択の根拠を監査不可能にする不透明な中間層が生まれます。

そこで、ここでは制御を逆転させています。予測ライブラリはツールであり、推論を行うのはあなたのエージェントです。エージェントは特徴量を読み取り、モデルファミリーについて議論し、候補を交差検証し、その根拠をマニフェストに書き込みます。途中のすべての数値は、LLMを介さずに再実行可能なライブラリ呼び出しによって生成されます。

この分割は、パッケージ自体の構築方法にも反映されています。基本インストールでは、statsforecastを介してAutoARIMA、AutoETS、Theta、CrostonClassicなどの11の統計モデルが実行されます。サイズは約340MB、PyTorchは不要で、起動は数秒です。オプションのfoundationエクストラを追加すると、TimeCopilotの事前学習済みモデル（Chronos、Moirai、TimesFM、TiRex、Totoなど）とProphetが追加され、統計的ベースラインでは不十分な場合に対応します。統計モデルのみを指定したリクエストでは、TimeCopilotやtorchはインポートされません。一方、1つでもファンデーションモデルを指定したリクエストは、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を介して11の統計モデルが実行されます。サイズは約340MB、PyTorchは不要で、即座に起動します。事前学習済みファンデーションモデル（Chronos、Moirai、TimesFM、Toto、TiRex）とProphetを追加するには、エクストラを追加します：

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

foundationエクストラはTimeCopilotをプルし、torch、transformers、lightningをもたらします。初回インストール時は約2GB、それに触れる最初のツール呼び出しではインポートに約30秒かかります。どちらも1回限りであり、それらを必要とするモデルを要求しない限り、費用は発生しません。

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

カジュアルなテスト以外では、refを固定してください。そうしないと、ブランチの先頭が移動する可能性があります。コミットは現在機能します。バージョンタグも、一度作成されれば機能します：

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サーバーを検出し、エージェントモードでツールを公開します。ツールはaskモードやeditモードでは表示されません。

VS Code。 サーバーを.vscode/mcp.jsonに配置してリポジトリと共有するか、コマンドパレットからMCP: Open User Configurationを実行して、すべてのワークスペースで自分のプロファイルに保持します。キーはmcpServersではなくserversであることに注意してください：

{
  "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ボタンを使用して8つのtsf_*ツールがリストされ、有効になっていることを確認します。MCP: List Serversはサーバーのステータスとログを表示し、起動に失敗した場合の説明がここに表示されます。Copilotは同時にアクティブにできるツールの数に上限があるため、複数のMCPサーバーを実行している場合は、8つすべてを収めるためにいくつかを選択解除する必要がある場合があります。

Visual Studio。 同じJSON形式で、ソリューションルートの.mcp.json（またはすべてのソリューションで%USERPROFILE%\.mcp.json）に配置し、Copilot Chatのエージェントモードツールピッカーからツールを有効にします。

JetBrains、Eclipse、Xcode。 Copilot Chatのエージェントモードツールピッカーを開き、Edit MCP configurationを選択し、開いたmcp.jsonに同じserversエントリを追加します。

Copilot coding agent（github.com上のクラウドエージェント）は、このサーバーには適していません。MCPサーバーを一時的なGitHub Actions環境内で実行するため、実行のたびに約2GBのTimeCopilotインストールを支払うことになり、ローカルデータファイルにアクセスできません。代わりにエディターから使用してください。

ツール

2つのtsf_export_*ツールを除くすべては読み取り専用としてマークされています。ここでは何も削除しないため、~/.tslab-mcp/runsのクリーンアップはあなたの責任であり、エージェントの責任ではありません。

セッションの開始

ツールは順序を強制しないため、開始プロンプトが8つの呼び出し可能な関数を分析に変えるものです。次のようなものがうまく機能します：

tslabツールを使用して、/Users/me/data/deposits.csvの系列を12ヶ月先まで予測してください。

この順序で作業し、各ステップで推論を示してください：

1. ファイルをロードし、見つけたものを教えてください — 系列数、頻度、ギャップや欠損値の有無。

2. 特徴量を説明し、それらがどのモデルファミリーを支持するか、そしてその理由を述べてください。

3. 提案する前に、実際にインストールされているモデルを確認してください。

4. ショートリストをSeasonalNaiveベースラインに対して4つのウィンドウで交差検証してください。今のところ統計モデルのみ。

5. 勝者で予測し、80%と95%の区間を付けてください。

6. 実行マニフェストとHTMLレポートをエクスポートし、モデル選択の根拠をノートに記入してください：何を選んだか、メトリックテーブルが何を示したか、何を却下したか。

結果を要約し、parquetパスを教えてください — フレーム全体をチャットに貼り付けないでください。

そのプロンプトで実際に機能している4つの要素：

• 絶対パス。 相対パスはサーバーのワーキングディレクトリに対して解決されます。これはMCPクライアントが選択し、通常は予測できません。

• 決定に一致する地平線。 hは予測と、各CVウィンドウが消費する履歴量の両方を決定します。12ヶ月ステップは1年の計画であり、任意のデフォルトではありません。

• 「今のところ統計モデルのみ。」 これがないと、エージェントはファンデーションモデルに手を伸ばし、AutoETSが数秒で解決するはずの質問に答えるために重みのダウンロードに数分を費やす可能性があります。安価なモデルが基準を設定したら、制限を解除してください。

• マニフェストノートに根拠を求めること。 チャットのトランスクリプトは使い捨てです。マニフェストは、誰かが再実行して監査できる部分です。推論が会話にしか存在しない場合、それは事実上失われます。

何をしたいかがわかっている場合の、より短い開始プロンプト：

/Users/me/data/sales.parquetをロードし、特徴量を説明してください。まだ予測しないでください — まず何を扱っているのか見たいのです。

ロードされたdepositsハンドルに対して、SeasonalNaive、AutoETS、AutoARIMAをh=12で6つのウィンドウにわたって比較し、ベースラインを十分に上回って追加の複雑さに見合うものがあるかどうかを教えてください。

統計のみの呼び出しは数秒で応答します。ファンデーションモデルを指定した最初の呼び出しは、他のことをする前にTimeCopilotのインポートに約30秒かかります。その一時停止は予想されるものであり、ハングではありません。また、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を埋め込み、外部スクリプト、スタイルシート、フォントを参照しないため、オフラインでも正しく開きます。

設計

4つの不変条件と、それらが存在する理由：

ハンドルであり、データフレームではない。 1つのクロスバリデーションフレームは n_series × h × n_windows × n_models 行になる。これをツール結果にシリアライズすると、最初の呼び出しでセッションのコンテキストを使い果たし、それ以降のすべてのターンを悪化させる。ツールはハンドルを受け取り、サマリー、集計、ファイルパスを返す。すべての一括パスには上限が設定され、省略した内容が報告されるため、セッションは再度問い合わせるのではなく、parquet を読むべきだと判断できる。

ブロッキング処理はイベントループに一切触れない。 大規模なパネルに対する複数モデルのクロスバリデーションは数分の CPU 時間を要する。すべてのツール本体は anyio.to_thread.run_sync 経由でディスパッチされる同期クロージャであるため、stdio トランスポートは応答し続け、クライアントが実行中にサーバーを切断することはない。

環境は推測されるのではなく、検出される。 モデルは遅延インポートされ、プローブされる。存在が前提とされることはない。tsf_list_models はここで実際に解決されたものを報告する。したがって、追加パッケージなしで Chronos を要求すると、実行開始から10分後にトレースバックが返る代わりに、不足している追加パッケージの名前を挙げたメッセージが返る。

バックエンドはリクエスト内容に応じて選択される。モデルがすべて統計モデルであるリクエストは statsforecast で実行され、事前学習済みモデルを必要とするリクエストだけが TimeCopilot を使用する。したがって、統計モデルの実行は torch をインポートすることがなく、どちらの場合でもサーバーは即座に起動する。

statsforecast は意図的にデフォルトの n_jobs=1 のままにされている。その並列モードは、エントリモジュールを再インポートするワーカープロセスを生成するが、MCP サーバー内では速度ではなく、競合と stdout の危険をもたらす。

マニフェストは記録の成果物である。 会話中の散文はコメントに過ぎない。マニフェストは、6か月後に誰かが再実行するものであり、レビュアーがどのモデルがどのような基準で比較されたかを確認するために読むものである。

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