KRA Racing Data Analysis MCP Server

Created By

coyaSONG6 months ago

한국 마사회의 공공API를 이용한 MCP server 입니다.

# data-analysis

# racing

Overview Content Tools Comments

Content

KRA Racing Data Analysis MCP Server

한국 마사회(Korea Racing Authority) 공공 API를 활용한 경마 데이터 분석 MCP 서버

이 프로젝트는 Model Context Protocol (MCP)을 사용하여 한국 마사회의 경마 데이터를 분석하고 인사이트를 제공하는 서버입니다.

🏇 주요 기능

🔧 분석 도구 (Tools)

analyze-race: 경주 분석 (날짜, 경주번호, 경마장별)
analyze-horse-performance: 말 성적 분석 및 폼 평가
get-jockey-stats: 기수 통계 및 성과 분석
analyze-odds: 배당률 분석 및 패턴 인식
analyze-track-condition: 주로 상태 및 날씨 영향 분석

📁 데이터 리소스 (Resources)

schedule://{date}: 경주 일정 정보 (오늘/내일)
horses://{horseName}: 말 상세 정보 및 기록
tracks://{trackCode}: 경마장 정보 (서울/부산/제주)
config://kra-api: KRA API 설정 및 구성

💬 분석 프롬프트 (Prompts)

predict-race: 경주 예측 분석 (기본/상세/통계)
horse-performance-report: 말 성적 상세 리포트
market-analysis: 마권 시장 분석 (배당률/거래량/트렌드)

🎯 활용 분야

경주 예측: 데이터 기반 경주 결과 예측
투자 분석: 마권 투자 전략 수립
성과 평가: 말, 기수, 조교사 성과 분석
시장 분석: 배당률 및 거래량 패턴 분석
리스크 관리: 투자 리스크 평가 및 관리

📦 설치 및 설정

필수 요구사항

Node.js 18.0.0 이상
npm 또는 yarn
한국 마사회 공공 API 접근 권한 ✅ 실제 연동 완료

KRA API 키 설정 (필수)

공공데이터포털 신청
- 공공데이터포털 접속
- "한국마사회 경주기록 정보" API 검색 및 신청
- 승인 후 서비스키 발급받기

환경변수 설정

# Windows (PowerShell)
$env:KRA_SERVICE_KEY="YOUR_SERVICE_KEY_HERE"

# macOS/Linux
export KRA_SERVICE_KEY="YOUR_SERVICE_KEY_HERE"

# 또는 .env 파일 생성
echo "KRA_SERVICE_KEY=YOUR_SERVICE_KEY_HERE" > .env

서비스키 확인
- URL 인코딩된 키를 사용해야 합니다
- 특수문자가 포함된 경우 인코딩 필요

프로젝트 설치

# 저장소 클론
git clone <repository-url>
cd kra-racing-data-mcp-server

# 의존성 설치
npm install

# KRA API 키 설정 (위 참조)
export KRA_SERVICE_KEY="your_service_key"

🏃‍♂️ 실행 방법

개발 모드

npm run dev

감시 모드 (파일 변경 시 자동 재시작)

npm run watch

프로덕션 빌드 및 실행

npm run build
npm start

🔧 MCP 클라이언트 등록

Cursor IDE에서 사용

~/.cursor/mcp.json 파일에 추가:

{
  "mcpServers": {
    "kra-racing-analysis": {
      "command": "npx",
      "args": ["tsx", "C:/Users/SONG/kra-racing-data-mcp-server/src/index.ts"]
    }
  }
}

프로덕션 버전 사용 시:

{
  "mcpServers": {
    "kra-racing-analysis": {
      "command": "node",
      "args": ["C:/Users/SONG/kra-racing-data-mcp-server/dist/index.js"]
    }
  }
}

Cursor 재시작 후 사용 가능합니다.

🧪 테스트 및 검증

MCP Inspector 사용

npx @modelcontextprotocol/inspector npx tsx src/index.ts

도구 테스트 예시

# 경주 분석 테스트
analyze-race --raceDate="2024-01-15" --raceNumber="3" --trackCode="seoul"

# 말 성적 분석 테스트
analyze-horse-performance --horseName="우승마" --period="1year"

📂 프로젝트 구조

kra-racing-data-mcp-server/
├── src/
│   └── index.ts              # 메인 서버 파일
├── dist/                     # 빌드된 JavaScript 파일
├── package.json              # 프로젝트 설정
├── tsconfig.json             # TypeScript 설정
├── .gitignore               # Git 제외 파일
└── README.md                # 프로젝트 문서

🔍 사용 예시

1. 경주 분석 요청

{
  "method": "tools/call",
  "params": {
    "name": "analyze-race",
    "arguments": {
      "raceDate": "2024-01-15",
      "raceNumber": 5,
      "trackCode": "seoul"
    }
  }
}

2. 말 정보 조회

{
  "method": "resources/read",
  "params": {
    "uri": "horses://우승마"
  }
}

3. 경주 예측 프롬프트

{
  "method": "prompts/get",
  "params": {
    "name": "predict-race",
    "arguments": {
      "raceDate": "2024-01-15",
      "raceNumber": "5",
      "analysisType": "detailed"
    }
  }
}

🛠️ 개발 가이드

새로운 분석 도구 추가

server.tool("new-analysis-tool",
  { 
    param1: z.string(),
    param2: z.number().optional()
  },
  async ({ param1, param2 }) => ({
    content: [{ 
      type: "text", 
      text: `분석 결과: ${param1} ${param2 || ''}` 
    }]
  })
);

새로운 데이터 리소스 추가

server.resource(
  "new-resource",
  new ResourceTemplate("resource://{id}", { list: undefined }),
  async (uri, { id }) => ({
    contents: [{
      uri: uri.href,
      text: JSON.stringify({ id, data: "..." }, null, 2)
    }]
  })
);