Claude Code로 Vibe-Trading MCP 퀀트 백테스터 구동

문장 하나만 입력하면 됩니다. "2024년 BTC-USDT 20/50 이동평균 전략을 백테스트해줘"라고 쓰면 자산 곡선까지 포함된 정량 리포트가 돌아옵니다. 이것이 Vibe-Trading의 핵심 제안이고, 흔한 원커맨드 데모들과 달리 그 아래의 배관은 실제로 작동합니다.

HKUDS가 만든 것: 말로 지시하는 퀀트 데스크

Vibe-Trading은 홍콩대학교 Data Intelligence Lab, 즉 LightRAG를 만든 HKUDS 팀이 공개한 MIT 라이선스 셀프호스팅 트레이딩 에이전트입니다. 자연어 지시를 실행 가능한 퀀트 리서치로 바꿔 백테스트, 약 15개 지표, 자산 곡선, 검증 산출물, 내보낼 수 있는 리포트까지 생성합니다 . 자연어는 인터페이스일 뿐 모델링 주장 자체는 아닙니다. 생성된 Python 코드는 여전히 로컬에서 실행되고, 데이터 로더도 기존의 커버리지 한계를 그대로 갖습니다. 이 프로젝트는 출시 후 몇 달 만에 대략 GitHub 스타 29,000개를 모았습니다. 빠르게 변하는 수치이므로 방향성 정도로 보는 편이 맞습니다.

눈에 띄는 것은 범위입니다. 내부에는 스크리너, 팩터 리서처, 백테스터, 리스크 감사자가 DAG로 연결된 멀티 에이전트 "스웜" 팀이 있고, 약 88개의 내장 금융 스킬 을 활용합니다. 여러 시장과 데이터 피드를 다루며, 대부분은 API 키가 필요 없습니다.

새로운 모델링 방식이라기보다는 에이전트형 퀀트 흐름을 엔지니어링 관점에서 한데 묶은 결과물로 보는 편이 정확합니다. 자연어 우선, MCP 네이티브, 폭넓은 멀티마켓 지원이 핵심입니다 . 한국어 해설 영상이 관심을 키웠지만, 실제 내용은 저장소에 있습니다.

의존성과 실행 전 체크리스트

설치하기 전에 네 가지를 확인해야 합니다. Python 런타임, LLM 공급자 키 1개, MCP 지원 클라이언트, 그리고 백테스트를 넘어설 계획이 있을 때만 필요한 브로커 자격 증명입니다. Vibe-Trading은 Python 3.11+가 필요하고, 0.1.x 라인이 빠르게 바뀌므로 최신 커밋을 따라가기보다 테스트한 정확한 버전을 고정하는 것이 좋습니다.

• LLM 공급자 키 1개: 스웜에는 OpenAI, Anthropic Claude, Google Gemini, DeepSeek, Kimi/Moonshot, Zhipu GLM, SiliconFlow, iFlytek Spark 중 하나의 공급자가 필요하거나, OpenAI 호환 어댑터를 통한 로컬 Ollama/vLLM 엔드포인트가 필요합니다. 약 88개의 내장 금융 스킬 대부분은 API 키 없이 실행되며, 공급자 키가 필요한 것은 스웜뿐입니다.
• MCP 클라이언트: stdio 서버를 구동하려면 Claude Code, Codex CLI 또는 MCP 호환 클라이언트가 필요합니다. Docker Compose는 선택 사항이지만, 사용하면 전체 프런트엔드가 localhost:8899에서 올라옵니다.
• 브로커 자격 증명: 백테스트만 사용할 때는 필요 없습니다. Alpaca와 IBKR 연동은 기본적으로 꺼져 있으며 명시적으로 선택해야 합니다.

Vibe-Trading을 한 번에 세팅하는 방법

Vibe-Trading 세팅은 세 가지 명령으로 설치한 뒤 드라이버를 고르면 됩니다. 빠른 스모크 테스트에는 독립 실행형 CLI를 쓰고, Claude Code가 모든 도구를 네이티브로 호출하게 하려면 MCP subprocess로 붙이면 됩니다. 먼저 패키지를 설치하세요: pip install vibe-trading-ai, 그다음 vibe-trading init를 실행합니다. init 단계는 기본 설정을 작성하고 현재 머신에서 사용할 수 있는 도구를 자동으로 찾아내므로, 실제로 키나 데이터가 있는 항목만 연결하면 됩니다 . Python 3.11 이상이 필요하며, 0.1.x 라인은 빠르게 바뀌고 있습니다 .

1단계 — CLI 테스트(MCP 클라이언트 불필요). 초기화가 끝나면 하나의 프롬프트로 리서치부터 리포트까지 전체 루프를 실행할 수 있습니다:

vibe-trading run -p "Backtest a BTC-USDT 20/50 MA strategy for 2024"

설치가 처음부터 끝까지 제대로 동작하는지 확인하는 가장 빠른 방법입니다. 브로커나 외부 클라이언트를 붙이지 않아도 데이터 로더, 백테스트 엔진, 지표, 리포트 내보내기까지 한 번에 점검합니다 .

2단계 — MCP 경로. Claude Code에서 구동하려면 MCP 설정에 Vibe-Trading을 stdio subprocess 항목으로 추가합니다. 그러면 Claude Code가 번들로 제공되는 약 88개의 금융 스킬을 네이티브 tool-call처럼 호출하고, waiting / running / done / failed 상태를 채팅 타임라인에 스트리밍하며, UI 연결이 끊긴 뒤에도 완료된 실행 카드를 다시 복원합니다 . 아래 예시 Python은 실행용이 아니라 설명용입니다. 실제 vibe-trading-mcp 명령은 패키지에 포함되어 있으며, Claude Code가 내부적으로 수행하는 원시 JSON-RPC 핸드셰이크를 보여줍니다:

#!/usr/bin/env python3
import json
import subprocess
import sys


def send(proc, msg):
    raw = json.dumps(msg).encode()
    proc.stdin.write(b"Content-Length: %d\r\n\r\n" % len(raw) + raw)
    proc.stdin.flush()


def recv(proc):
    headers = {}
    while True:
        line = proc.stdout.readline()
        if line in (b"\r\n", b"\n", b""):
            break
        k, v = line.decode().split(":", 1)
        headers[k.lower()] = v.strip()
    body = proc.stdout.read(int(headers["content-length"]))
    return json.loads(body)


run_dir = "vt_mcp_demo_run"  # Claude Code would create config/code here first.
print("Claude Code -> Vibe-Trading MCP -> backtest(run_dir=%r)" % run_dir)

try:
    p = subprocess.Popen(
        ["vibe-trading-mcp"],
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
    )
except FileNotFoundError:
    print("vibe-trading-mcp not found; install with: pip install vibe-trading-ai")
    sys.exit(1)

send(p, {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-03-26", "capabilities": {}, "clientInfo": {"name": "claude-code-demo", "version": "0"}}})
print("initialized:", recv(p).get("result", {}).get("serverInfo", {}).get("name"))
send(p, {"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}})
send(p, {"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "backtest", "arguments": {"run_dir": run_dir}}})
print(json.dumps(recv(p), indent=2)[:1200])
p.terminate()

Docker Compose 대안. 웹 UI를 선호한다면 docker compose up으로 백엔드와 프론트엔드를 localhost:8899에서 띄우고 SSE 스트리밍을 사용할 수 있습니다 . 이후에는 약 30개의 번들 swarm preset을 바로 실행할 수 있습니다. 예를 들어 quant_strategy_desk는 screener → factor researcher → backtester → risk auditor를 DAG로 연결해, 하나의 지시가 단일 에이전트가 아니라 조율된 전문가 팀 전체로 퍼져 나가게 합니다 .

Vibe-Trading이 판단을 흐릴 수 있는 지점

편리함 뒤에는 결과를 신뢰하기 전에 짚고 넘어가야 할 세 가지 실패 모드가 있습니다. 첫째, 자연어는 인터페이스일 뿐 정확성을 보장하지 않습니다. 문서는 성능이 약한 모델은 도구를 호출하는 대신 학습 데이터에서 답을 지어낼 수 있다고 경고합니다 . 즉, 약 88개의 번들 금융 도구가 실제로 호출되는지 여부는 모델 역량에 달려 있습니다 . 백테스터를 전혀 실행하지 않은 자신감 있는 문단도, 실제로 실행한 문단과 겉보기에는 똑같습니다.

둘째, 대표 숫자는 설명용으로 봐야 합니다. "연율 12.3%, Sharpe 1.4" 같은 데모 수치는 예시일 뿐 독립적으로 평가된 결과가 아닙니다 . 또한 Vibe-Trading을 TradingAgents나 FinRL-Meta와 정면 비교한 동료 심사 연구도 아직 없습니다. 생존자 편향, 생성 코드의 신뢰성, 그리고 LLM 에이전트 프레임워크가 거래 비용 이후에도 지속 가능한 표본 외 알파를 만들어낼 수 있는지에 대해서는 여전히 열린 질문이 남아 있습니다 .

셋째, 안전성 설명은 그럴듯하지만 자체 보고에 가깝습니다. 생성된 전략 코드는 AST로 강화된 샌드박스에서 실행되어 네트워크 접근, subprocess 호출, eval(), os.environ 읽기를 차단합니다 . 그러나 실제 사용자 데이터를 대상으로 한 프롬프트 인젝션 내성은 독립 감사자가 검증한 적이 없습니다. 팀은 자체 보안 감사를 2026-07-10에 완료했으며, 실거래 가드레일인 mandate gate, 파일시스템 kill-switch, 전체 감사 원장도 이 내부 검토에만 기대고 있습니다 . 유지관리자들의 설명에 따르면 키는 기본적으로 생성 코드에 제공되지 않고, 중대한 브로커 쓰기 작업은 "require human approval"을 요구하며, 읽기는 자동 승인됩니다 — Vibe-Trading team, HKUDS (source: GitHub). 운영상 한 가지 더 주의할 점은, 지갑 "verification" 사기로 프로젝트를 사칭하는 피싱 Discord가 있으며 이는 프로젝트 측의 것이 아니라는 점입니다 . 팀에 공유해 두세요.

먼저 해볼 만한 퀀트 실험

데스크가 돌아가기 시작하면 이를 신호 생성기가 아니라 리서치 샌드박스로 보고, 데모 숫자가 건너뛰는 부분에 부담을 주는 실험부터 골라보는 편이 좋다. Vibe-Trading에는 워크포워드, 몬테카를로와 부트스트랩 검증, 미국 주식과 한국 KRX를 포함한 여러 시장을 아우르는 9개 백테스트 엔진, 약 15개 지표, 사전 구축된 팩터 모음인 Alpha Zoo가 포함되어 있다 . 실제 자본을 투입하기 전에 전략을 제대로 따져볼 만큼의 도구는 갖춘 셈이다.

• 미국 또는 KRX 유니버스에서 멀티팩터 스크리너를 워크포워드로 검증하기. README의 “연환산 12.3%, 샤프 1.4” 같은 예시 수치가 결코 입증하지 못하는 부분이 바로 표본 외 일관성이다 .
• 암호화폐 모멘텀 전략을 몬테카를로로 점검하기. OKX 또는 CCXT 데이터를 1분에서 1일 봉 단위로 사용한 뒤, 단일 수익률 숫자가 아니라 내장된 약 15개 지표에 비추어 결과를 읽어야 한다 .
• Alpha Zoo 팩터군 비교하기. 하나의 백테스트 구간에서 Qlib, Kakushadze-101, GTJA-191 신호를 돌려 거래비용 이후에도 살아남는 팩터가 무엇인지 확인한다 .
• Shadow Account 모드 써보기: 실제 거래 이력을 연결하면 에이전트가 운용 규칙을 자동으로 추출한다. 라이브 브로커를 연결하기 전에 자신의 행동 패턴을 낮은 위험으로 감사해볼 수 있는 방법이다 .

핵심은 이렇다. 자연어 루프를 활용해 평소라면 건너뛰었을 실험을 실행하되, 모든 결과는 직접 검증해야 한다. 아직 어떤 LLM 에이전트 퀀트 프레임워크에서도 지속 가능한 표본 외 알파가 나온다는 점을 확인한 동료심사 벤치마크는 없다 .

자주 묻는 질문

Vibe-Trading을 쓰려면 유료 데이터 구독이 필요한가?

아니다. yfinance, AKShare, CCXT, OKX, Finnhub 무료 티어를 포함해 번들로 제공되는 24개 데이터 소스 대부분은 API 키 없이 작동하며, Vibe-Trading은 시장별로 가장 적합한 무료 소스를 자동 선택한다 . Tushare는 무료 등록 토큰이 필요하고, 더 정밀한 데이터를 원할 경우 선택형 프리미엄 QVeris 게이트웨이도 있지만, 백테스트 실행에 둘 다 필수는 아니다 . 제공자 키가 필요한 것은 LLM 스웜뿐이다.

금융 도구를 호출할 때 가장 신뢰할 만한 결과를 내는 LLM은 무엇인가?

프런티어 모델을 쓰는 것이 가장 안전하다. Vibe-Trading은 약 88개의 금융 스킬을 제공하고 도구 호출 비중이 높기 때문에, 문서에서는 약한 모델이 도구를 호출하는 대신 학습 데이터에 기반해 답을 지어낼 수 있다고 경고한다. 따라서 모델 성능이 신뢰성에 직접적인 영향을 준다 . Anthropic Claude, OpenAI GPT-4o, Google Gemini처럼 성능이 좋은 제공자가 가장 무난한 선택지다. 로컬 Ollama나 vLLM은 OpenAI 호환 어댑터를 통해 실행할 수 있지만, 파라미터 수가 작은 모델일수록 신뢰성은 떨어진다 .

Vibe-Trading을 라이브 브로커에 연결해도 안전한가?

신중하게 다루고, 가능하면 읽기 전용으로 유지하는 것이 좋다. IBKR 경로는 주문 실행 도구가 등록되지 않은 읽기 전용이며, Alpaca의 TAP 모드는 기본적으로 꺼져 있고 원시 브로커 키를 에이전트 프로세스 밖에 보관하며 주문과 취소처럼 결과가 큰 쓰기 작업에는 사람의 승인을 요구한다 . 라이브 트레이딩은 종목 유니버스, 포지션 크기, 익스포저, 레버리지, 일일 한도에 따라 운용 지침으로 제한되며, 파일시스템 킬스위치와 감사 원장도 둔다. 팀은 2026-07-10에 보안 감사가 완료됐다고 보고했지만, 기본 관점은 여전히 리서치와 시뮬레이션 우선이다.

Vibe-Trading은 MCP 클라이언트 없이 CLI만으로 실행할 수 있나?

그렇다. vibe-trading run -p "your prompt"를 실행하는 방식은 MCP 클라이언트가 필요 없는 완전한 독립 실행 경로다 . MCP 서버는 여러 인터페이스 중 하나일 뿐이다. 이 프로젝트는 CLI, localhost:8899의 FastAPI 웹 UI, 예약 작업, SSE 스트림, IM/채널 어댑터도 제공한다 . MCP가 중요한 경우는 Claude Code나 Codex CLI 같은 기존 어시스턴트가 이를 stdio 서브프로세스로 구동하게 만들고 싶을 때다.

Vibe-Trading은 FinGPT나 FinRL과 어떻게 다른가?

해결하려는 문제가 다르다. FinGPT(arXiv:2306.06031)는 LoRA/QLoRA로 금융 LLM을 미세조정해 분류와 감성 분석에 쓰며 수치 추론에는 약한 편이고, FinRL-Meta(arXiv:2304.13174)는 강화학습 전략을 위한 gym 스타일 RL 환경을 만든다. 반면 Vibe-Trading은 프런티어 LLM을 교체 가능한 제공자로 사용하고, 도구 호출 및 MCP 표면을 노출하며, 모델 학습이나 환경 엔지니어링보다 “전략을 설명하면 백테스트 리포트를 받는” 흐름에 초점을 맞춘다 . 이는 모델링 혁신이라기보다 배포와 오케스트레이션을 한곳에 모은 도구에 가깝다.

이 글이 도움이 되셨다면, 새 글이 올라올 때마다 이메일로 받아보세요.

구독하기