KBO Analyst

"잘하네"에서 멈추지 않고, "왜 잘하는지"까지 설명하는 KBO 데이터 엔진

KBO 경기를 투구 하나 단위(145만 구+)로 내 컴퓨터의 데이터베이스 파일 하나에 쌓고, 검증된 지표 계산식 45종과 분석 도구 28종(MCP)으로 팬의 "왜?"에 숫자 근거가 붙은 답을 만든다. 서버도, 인증키도, 비용도 필요 없다.

이런 답이 나온다

아래는 전부 이 저장소의 실제 조회 결과다 (2026-07-10 기준 DB).

"A 선수, 올해 왜 잘해?" — 타자의 공 고르기

2025 → 2026, 한가운데 높이 코스에 방망이가 나가는 비율이 −9~11%p. 스트라이크존 밖 유인구에 손대는 비율(Chase%)도 30.9 → 27.7%. 스윙 자체는 줄었는데(47.7 → 45.5%) 타격 종합 지표 wOBA는 .370 → .430으로 올랐다. 덜 치는데 더 잘 친다 — 나쁜 공을 골라내기 시작했다는 뜻이다. — kbo_approach_change (2025년 1,658구 vs 2026년 1,189구)

"ERA 3점대던데, 아직 괜찮은 거지?" — 투수 노쇠화 신호

겉보기 평균자책점은 3.91로 멀쩡하다. 그런데 평균 구속 133.6 → 132.3km/h, 헛스윙 유도율(Whiff%) 20.0 → 14.8%, 삼진 비율 14.2%로 구위 지표가 전부 같은 방향으로 내려갔다. 수비 도움을 걷어내고 투수 실력만 남긴 지표(FIP)는 5.39다. 이럴 때는 ERA보다 먼저 경고를 읽어야 한다. — pitcher_overview 시즌 비교 (2026년 1,366구)

"배트 스피드 죽었다던데, 진짜야?" — 잴 수 없는 것을 간접 지표로.

배트 스피드는 KBO 어디에도 공개되지 않아 직접 잴 수 없다. 대신 145km/h 이상 빠른 공을 상대했을 때의 헛스윙률을 본다: 2025년 17.5% → 2026년 25.2% (417구 → 356구). "빠른 공에 방망이가 늦는다"는 신호는 이렇게 숫자로 남는다. — batter_velo_band (계산 방식은 아래 표 참고)

"저러다 갈리는 거 아니야?" — 불펜 운용 · LG

2026년 불펜 등판 42회로 리그 최상위권. 이틀 연속 등판 9회, 한 주 최대 5등판. 3연투 / 7일간 4등판 이상 / 14일간 200구 이상 같은 기준을 넘기면 자동으로 경고 표시가 붙는다. — kbo_usage_pattern

"무사 1루, 번트가 맞아?" — 작전 판단 · 리그 전체

무사 1루에서는 이닝이 끝날 때까지 평균 0.96점이 난다. 번트가 성공해 1사 2루가 되면 이 기대치는 0.85점으로 줄어든다 — 성공해도 평균 0.11점 손해라는 뜻이다. 올해 실제로 시도된 희생번트 337회의 평균 득점 기여도 −0.05점이었다. "번트는 밑지는 장사"가 이 DB의 실제 수치로 확인된다. — re24_matrix · kbo_linear_weights_season

모든 답에는 근거가 된 데이터 양(표본)과 지표의 뜻이 함께 붙는다.

Related MCP server: mcp-sqlite3

어떤 질문에 답하나

3분 시작

git clone https://github.com/SNGCHN/kbo-analyst && cd kbo-analyst
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt        # requests lxml numpy matplotlib

경기 데이터는 저장소에 들어 있지 않다. 네이버 공개 API에서 직접 받는다 (가입·인증 필요 없음):

python3 collector.py 2026-06-10 2026-07-10       # 최근 한 달 — 몇 분
python3 collector.py 2026-03-21 2026-07-10 --workers=10   # 시즌 전체
python3 collector.py 2026-03-21 2026-07-10 --team=LG      # 한 팀만 (~5배 빠름)

이미 받은 경기는 알아서 건너뛰기 때문에, 중간에 끊고 다시 실행해도 이어서 받는다. 받은 다음:

python3 analysis.py validate --season 2026    # 공식 기록과 맞는지 대조
python3 analysis.py batters --season 2026 --min-pitches 20
python3 savant.py dashboard 최정 2026          # PNG 대시보드 생성

Claude Code / MCP로 쓰기

이 폴더를 Claude Code로 열면 .mcp.json이 로컬 분석 서버(kbo-local)를 자동 등록한다. 질문을 던지면 Claude가 아래처럼 도구를 골라 답한다. 해설 규칙·수집 운영·시각화·용어집 스킬까지 함께 쓰려면 .claude-plugin/plugin.json 기준으로 플러그인을 설치하면 된다.

"A 선수 2026 시즌, 작년보다 뭐가 달라졌어?"
"A팀 불펜이 최근 30일 혹사였는지 근거 보여줘"
"시즌 카드 만들어줘"

조회할 때 auto_collect=true를 주면 빠진 경기가 적을 때(15경기 이하)는 자동으로 채우고, 많이 빠졌으면 어느 범위를 받아야 하는지 알려준다. 모든 응답에는 데이터가 얼마나 완전한지 경고가 함께 붙는다. 더 깊은 분석은 kbo_sql(읽기 전용 SQL)로 지표 뷰 45종을 직접 조회한다.

잴 수 없는 것에 답하는 방법

KBO 공개 데이터에는 배트 스피드, 타구 속도, 타구 각도, 공 회전수가 없다 (유료 사이트에도 없다 — 구단만 가진 장비 데이터라서). 이런 질문을 받으면 숫자를 지어내는 대신, 가지고 있는 측정값을 조합해 "대신 볼 수 있는 간접 지표"를 만들고, 간접 지표라는 사실을 답에 함께 밝힌다.

답변은 "직접 잰 값 / 계산으로 얻은 값 / 추정"을 구분해서 말하도록 규칙이 잡혀 있다. 각 지표의 정확한 정의와 계산식은 METRICS.md에 있다.

숫자 검증

• 수집한 데이터를 경기마다 투수별 공식 기록(삼진/볼넷/피안타/홈런/투구 수)과 빠짐없이 대조한다(validate). 대조에 실패한 시즌은 답변에 경고가 붙는다.

• 기대 점수(RE24) 계산의 검산: 이 방식으로 더한 팀 득점이 공식 득점과 847/848 경기-팀에서 일치(총 오차 1점), 타석의 99.7%에 점수 기록이 붙어 있다 (2026-07-10 기준 424경기).

• 안타·홈런이 각각 몇 점 가치인지 실제 데이터로 계산한 결과가 야구 통계학의 표준 순서와 일치: 홈런 +1.72, 3루타 +1.51, 2루타 +1.15, 안타 +0.80, 볼넷 +0.66, 아웃 ≈ 0 (2026시즌, 평균적인 아웃 대비).

• python3 test_core.py — 자동 테스트 7종. push마다 CI로 돈다.

알려진 한계: wOBA/wRC+는 근사치다. 특히 wRC+ 뷰 두 개는 계산 기준이 달라 서로 비교하면 안 된다(METRICS.md 참고). RE24는 점수가 수집된 경기(2026-07 이후 수집분)만 반영한다. 승리 확률(WE/WPA)은 아직 없다.

시각화

python3 plot.py 후라도 2026-06-03        # 특정일 투구 위치맵
python3 card.py 김건우 2026              # 시즌 카드
python3 zone.py 최정 2026 --metric woba  # 존 히트맵
python3 savant.py dashboard 김건우 2026  # 종합 대시보드

PNG는 charts/에 생성되고, MCP로 요청하면 이미지가 답변에 바로 포함된다. 한글 폰트는 macOS·Windows·Linux에 설치된 폰트를 순서대로 찾는다.

저장소 구성

로드맵

• 2020~2025 시즌 점수 다시 받기 → 시즌별 기대 점수(RE24) 완성

• 승리 확률(WE/WPA) — 점수·이닝·주자 상황이 모두 있어 자체 계산 가능

• wRC+ 두 뷰의 계산 기준 통일

• 연봉·계약 데이터 수집 (프런트 평가용)

주의사항

원본 데이터는 네이버 스포츠 공개 API와 KBO 공식 사이트에서 수집한다. 이 저장소는 코드만 배포하며 수집된 kbo.db는 배포하지 않는다. 개인 분석과 교육 목적으로 쓰고, 수집기의 기본 대기·재시도 설정을 그대로 둘 것.

License

MIT