국내주식 자동매매 시뮬레이터

한국 주식시장을 대상으로 한 페이퍼 트레이딩 자동매매 시스템. 실제 주문 없이 전략을 검증합니다.

MCP 서버를 직접 구현해 Claude Desktop에서 대화만으로 전략 파라미터를 바꾸고 백테스트를 실행할 수 있는 것이 특징입니다.

⚠️ 학습·연구 목적의 시뮬레이터입니다. 실제 주문은 실행하지 않습니다.

구조

Docker Compose로 4개 서비스가 함께 뜹니다.

헬스체크를 통과한 뒤에 다음 서비스가 시작하도록 기동 순서를 보장했습니다.

Related MCP server: Korean Finance MCP Server

매매 전략

매수는 두 관문을 모두 통과해야 합니다.

1. 변동성 돌파 — 전일 변동폭에 계수를 곱한 기준선을 돌파

2. XGBoost 확률 필터 — 학습된 모델의 상승 확률이 임계값 이상

매도는 손절·익절 기준에 도달하면 자동 실행됩니다. 모든 임계값은 설정에서 단일 출처로 관리합니다.

설계 패턴

Strategy + Registry 전략을 인터페이스로 추상화하고 데코레이터로 등록합니다. 새 전략을 추가할 때 기존 코드를 수정할 필요가 없습니다.

의존성 역전 주문 실행부를 팩토리로 주입받습니다. 페이퍼 트레이딩과 실거래 구현을 갈아끼울 수 있는 구조입니다.

Firestore 원자적 배치 포지션과 잔고 갱신을 하나의 배치로 묶어 부분 실패를 방지합니다.

알림 실패 격리 알림 전송이 실패해도 매매 로직은 중단되지 않도록 예외를 흡수합니다.

MCP 서버

FastMCP 기반 stdio transport로 구현했습니다. Claude Desktop에 연결하면 대화로 시스템을 조작할 수 있습니다.

• 도구 7개 노출 — 포지션 조회, 전략 파라미터 변경, 백테스트 실행 등

• 모든 도구에 @_safe 데코레이터를 적용해 예외를 dict로 변환 → 서버 오류로 클라이언트가 죽지 않습니다

• 파라미터를 변경하면 다음 매매 사이클부터 즉시 반영됩니다

백테스트

과거 데이터로 전략을 검증하는 엔진을 포함합니다. 승률, 손익비, 누적 수익률을 계산합니다.

실행

cp .env.example .env      # 설정 입력
docker compose up

기술 스택

Python Django 5.2 Celery Celery Beat Redis Firebase/Firestore XGBoost pykrx Docker Compose FastMCP pytest

프로젝트 구조

src/
  strategies/    전략 인터페이스 · 레지스트리 · 구현체
  executors/     주문 실행 (페이퍼 / 실거래)
  backtest/      백테스트 엔진
  mcp/           MCP 서버
  notify/        알림
config/          설정 단일 출처
tests/           단위 테스트

개발 배경

이 프로젝트는 컴퓨터 초기화로 소스를 유실한 적이 있습니다. 다행히 아키텍처와 설계 결정을 정리해 둔 CLAUDE.md 문서가 남아 있어, 그 문서를 기준으로 코드를 재구성했습니다. 설계 문서를 남겨두는 습관의 가치를 체감한 경험입니다.