tslab-mcp

시계열 예측을 도구로 노출하는 MCP 서버로, 모든 예측값은 일반적이고 재현 가능한 Python에서 비롯됩니다. 에이전트는 추론 엔진 역할을 합니다.

이 패키지 어디에서도 LLM을 호출하지 않습니다. API 키가 필요하지 않습니다(단, Nixtla API를 호출하는 TimeGPT를 요청하는 경우는 제외).

이유

일부 예측 라이브러리에는 LLM이 내장된 에이전트가 포함되어 있어, 특징을 읽고 모델을 선택한 후 결과를 설명합니다. 이러한 라이브러리를 자체 에이전트에서 호출하면 에이전트 안에 에이전트가 중첩되어, 두 번의 프롬프트, 두 번의 비용, 두 가지 비결정적 요소, 그리고 모델 선택 근거를 감사할 수 없게 만드는 불투명한 중간 계층이 생깁니다.

따라서 여기서는 제어가 역전됩니다. 예측 라이브러리는 도구가 되고, 에이전트는 추론합니다. 특징을 읽고, 모델군에 대해 논쟁하며, 후보들을 교차 검증하고, 그 근거를 매니페스트에 기록합니다. 경로에 LLM 없이도 재실행할 수 있는 라이브러리 호출로 모든 숫자가 생성됩니다.

이러한 분리는 패키지 자체의 구성 방식에도 반영됩니다. 기본 설치는 statsforecast를 통해 AutoARIMA, AutoETS, Theta, CrostonClassic 등 11개의 통계 모델을 실행합니다. 약 340MB, 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를 통해 11개의 통계 모델을 실행합니다. 약 340MB, PyTorch 없이 즉시 시작됩니다. 사전 훈련된 기반 모델(Chronos, Moirai, TimesFM, Toto, TiRex) 및 Prophet을 추가하려면 확장 기능을 설치하세요:

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

foundation 확장 기능은 TimeCopilot을 가져오며, 여기에는 torch, transformers 및 lightning이 포함됩니다. 첫 설치 시 약 2GB, 처음 도구 호출 시 약 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

테스트가 아닌 경우에는 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"]
    }
  }
}

그런 다음: 채팅을 열고 모드 선택기를 Agent로 전환한 후 Tools 버튼을 사용하여 8개의 tsf_* 도구가 나열되고 활성화되었는지 확인하세요. MCP: List Servers는 서버의 상태와 로그를 보여주며, 시작 실패 시 원인을 확인할 수 있습니다. Copilot은 한 번에 활성화할 수 있는 도구 수에 제한이 있으므로, 여러 MCP 서버를 실행하는 경우 일부를 선택 해제해야 할 수 있습니다.

Visual Studio. 동일한 JSON 형식으로, 솔루션 루트(또는 모든 솔루션의 경우 %USERPROFILE%\.mcp.json)의 .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 설치 비용이 발생하며 로컬 데이터 파일에 접근할 수 없습니다. 대신 에디터에서 사용하세요.

도구

tsf_export_* 두 도구를 제외한 모든 도구는 읽기 전용으로 표시됩니다. 여기서 삭제 작업은 수행되지 않으므로, ~/.tslab-mcp/runs 정리는 사용자의 책임입니다.

세션 시작하기

도구는 순서를 강제하지 않으므로, 여는 프롬프트가 8개의 호출 가능한 함수를 분석으로 전환합니다. 다음과 같은 방식이 효과적입니다:

tslab 도구를 사용하여 /Users/me/data/deposits.csv의 계열을 12개월 앞으로 예측하세요.

다음 순서로 작업하고 각 단계에서 추론을 보여주세요:

1. 파일을 로드하고 발견한 내용을 알려주세요 — 몇 개의 계열, 주기, 간격이나 누락값이 있는지.

2. 특징을 설명하고, 어떤 모델군이 적합한지, 그 이유를 말하세요.

3. 모델을 제안하기 전에 실제로 설치된 모델을 확인하세요.

4. 후보 목록을 4개 윈도우에 대해 SeasonalNaive 기준선과 교차 검증하세요. 지금은 통계 모델만 사용.

5. 승자로 80% 및 95% 예측 구간을 포함한 예측.

6. 실행 매니페스트와 HTML 보고서를 내보내고, 모델 선택 근거를 노트에 기록하세요: 무엇을 선택했는지, 메트릭 표가 무엇을 보여주었는지, 무엇을 기각했는지.

결과를 요약하고 parquet 경로를 알려주세요 — 전체 프레임을 채팅에 붙여넣지 마세요.

해당 프롬프트에서 실제로 중요한 네 가지 사항:

• 절대 경로. 상대 경로는 서버의 작업 디렉터리를 기준으로 해석되며, 이는 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      |

높은 계절성 강도와 명확한 추세는 naive 기준선보다 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은 항상, TimeCopilot과 torch는 foundation 확장 기능이 있으면 포함), 그리고 노트가 포함됩니다. 서버가 중지된 상태에서도 숫자를 재현하기에 충분합니다.

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_시계열 × h × n_윈도우 × n_모델 행으로 구성됩니다. 이를 도구 결과로 직렬화하면 첫 번째 호출에서 세션의 컨텍스트를 소진하고 이후의 모든 턴을 악화시킵니다. 도구는 핸들을 받아 요약, 집계, 파일 경로를 반환합니다. 모든 대량 경로는 상한이 있고 생략된 내용을 보고하므로, 세션은 다시 요청하는 대신 parquet 파일을 읽어야 함을 알게 됩니다.

차단 작업은 이벤트 루프를 건드리지 않습니다. 대규모 패널에 대해 여러 모델을 교차 검증하는 것은 수 분의 CPU 시간이 소요됩니다. 모든 도구 본체는 anyio.to_thread.run_sync를 통해 디스패치되는 동기 클로저이므로, stdio 전송이 계속 응답하고 클라이언트가 실행 중에 서버를 끊지 않습니다.

환경은 추정되지 않고 발견됩니다. 모델은 지연 로딩되고 탐색되며, 존재한다고 가정되지 않습니다. tsf_list_models는 여기서 실제로 확인된 것을 보고하므로, 추가 패키지 없이 Chronos를 요청하면 실행 10분 후의 트레이스백 대신 해당 추가 패키지를 명명하는 메시지를 반환합니다.

백엔드는 요청 내용에 따라 선택됩니다. 모든 모델이 통계적 모델인 요청은 statsforecast를 통해 실행되고, 사전 학습된 모델이 필요한 요청만 TimeCopilot에 도달합니다. 따라서 통계적 실행은 절대 torch를 임포트하지 않으며, 어느 경우든 서버는 즉시 시작됩니다.

statsforecast는 의도적으로 기본값 n_jobs=1로 유지됩니다. 병렬 모드는 작업자 프로세스를 생성하여 진입 모듈을 다시 임포트하는데, MCP 서버 내부에서는 속도 향상보다는 경합과 stdout 위험을 초래합니다.

매니페스트가 기록의 대상입니다. 대화의 서술은 주석입니다. 매니페스트는 누군가가 6개월 후에 재실행할 대상이며, 리뷰어가 어떤 모델이 어떤 기준으로 비교되었는지 확인하기 위해 읽는 대상입니다.

파이썬 버전

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 인스펙터로 도구 표면을 검사합니다:

npx @modelcontextprotocol/inspector uv run tslab-mcp

라이선스

MIT