⚽🏀 SportsPulse MCP

Claude Desktop에서 실시간 스포츠 데이터를 사용할 수 있게 해주는 MCP 서버

🆓 사용하는 무료 API

API	비용	데이터
TheSportsDB	완전 무료 (key: 3)	팀 일정, 결과, 맞대결, 순위
balldontlie.io	완전 무료 (키 불필요)	NBA 경기, 선수 스탯
API-Football	무료 100req/day	🔴 라이브 스코어, 실시간 순위

⚡ TheSportsDB + balldontlie 만으로도 바로 사용 가능!
API-Football은 선택사항 (라이브 스코어 원할 때만 발급)

---

🚀 설치 방법

1. 의존성 설치 & 빌드

git clone <this-repo>
cd sports-mcp
npm install
npm run build

2. 환경 변수 설정

cp .env.example .env
# .env 파일에서 RAPIDAPI_KEY 값만 교체 (선택사항)

3. Claude Desktop 설정

Claude Desktop 설정 파일을 열고:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

아래 내용을 추가 (경로는 본인 환경에 맞게 수정):

{
  "mcpServers": {
    "sports-pulse": {
      "command": "node",
      "args": ["/Users/yourname/sports-mcp/dist/index.js"],
      "env": {
        "SPORTSDB_API_KEY": "3",
        "RAPIDAPI_KEY": "your_rapidapi_key_here"
      }
    }
  }
}

4. Claude Desktop 재시작

설정 저장 후 Claude Desktop을 완전히 종료 후 재시작하면 tools 아이콘(🔧)에 스포츠 도구들이 나타납니다!

---

💬 사용 예시

Claude Desktop에서 이렇게 물어보세요:

"오늘 EPL 경기 있어?"
"손흥민 다음 경기 언제야?"
"맨시티 최근 5경기 결과 알려줘"
"EPL 순위 보여줘"
"맨유 vs 리버풀 역대 전적이 어때?"
"레이커스 오늘 경기 했어?"
"LeBron James 이번 시즌 스탯 어때?"
"내 관심팀 토트넘이랑 레이커스 이번 주 경기 브리핑해줘"

---

🛠️ 지원 도구 (Tools)

Tool	설명	필요 API
get_live_scores	🔴 라이브 스코어	API-Football
get_today_fixtures	오늘 경기 일정/결과	API-Football
get_upcoming_fixtures	팀 다음 경기 일정	TheSportsDB
get_recent_results	팀 최근 경기 결과	TheSportsDB
get_standings	리그 순위표	둘 다 시도
get_head_to_head	맞대결 기록	TheSportsDB
get_nba_today	NBA 오늘 경기	balldontlie
get_nba_team_games	NBA 팀 최근 경기	balldontlie
get_nba_player_stats	NBA 선수 스탯	balldontlie
get_weekly_briefing	관심팀 주간 브리핑	TheSportsDB + balldontlie

---

🔧 트러블슈팅

Q: Claude에서 tool이 안 보여요

• dist/index.js 파일이 있는지 확인 (npm run build 재실행)
• config.json의 args 경로가 절대경로인지 확인
• Claude Desktop 완전 재시작 (메뉴바에서 완전 종료)

Q: "팀을 찾을 수 없습니다" 오류

• 영어 팀 이름으로 시도 (예: "Tottenham" 대신 "Tottenham Hotspur")
• TheSportsDB에서 팀명 검색 확인: https://www.thesportsdb.com/api/v1/json/3/searchteams.php?t=Tottenham

Q: 라이브 스코어가 안 돼요

• .env의 RAPIDAPI_KEY 확인
• 무료 100req/day 초과 여부 확인

---

📦 프로젝트 구조

sports-mcp/
├── src/
│   ├── index.ts          # MCP 서버 메인 + 모든 tool 핸들러
│   ├── types.ts           # 공통 타입 정의
│   ├── utils.ts           # 시간대 변환, 팀 이름 정규화
│   └── adapters/
│       ├── sportsdb.ts    # TheSportsDB API
│       ├── nba.ts         # balldontlie.io NBA API
│       └── apifootball.ts # API-Football (RapidAPI)
├── dist/                  # 컴파일 결과 (npm run build 후 생성)
├── .env.example
├── package.json
└── tsconfig.json