Sleeper Fantasy Football MCP Server

Sleeper의 판타지 풋볼 공개 API를 래핑하는 원격 MCP(Model Context Protocol) 서버입니다. HTTP 서비스(Streamable HTTP transport)로 실행되므로 인터넷을 통해 Claude Desktop 및 Claude 모바일 앱에서 접근할 수 있습니다. 드래프트 도중에 휴대폰으로 리그 데이터를 가져올 때 유용합니다.

Sleeper의 API(https://api.sleeper.app/v1/, 문서)는 공개되고 읽기 전용이므로, 이 서버는 리그 설정, 로스터, 픽을 절대 건드리지 않습니다 — 읽기만 수행합니다.

상태

이것은 초기 스캐폴드입니다. get_league_settings라는 하나의 도구가 Streamable HTTP 및 Bearer 토큰 인증과 함께 종단 간(end-to-end)으로 동작합니다. 더 많은 도구(로스터, 매치업, 드래프트 픽 등)는 src/tools.js에서 동일한 패턴을 따를 것입니다.

Related MCP server: Yahoo Fantasy Baseball MCP Server

프로젝트 구조

src/
  config.js         # reads env vars once, exports a typed config object
  sleeperClient.js   # thin wrapper around Sleeper's REST API
  auth.js            # bearer token middleware
  tools.js           # MCP tool definitions (registered against an McpServer)
  server.js          # express app: /health, /mcp, auth wiring, listen()
.env.example

새 도구를 추가하는 방법은 다음과 같습니다. sleeperClient.js에 fetch 함수를 추가하고, 그 함수를 호출하는 도구를 tools.js에 등록하면 됩니다. server.js와 auth.js는 변경할 필요가 없습니다.

사전 요구 사항

• Node.js 24.16.0 — package.json의 engines 항목에 고정됨

• Sleeper 리그 ID와 사용자 ID

리그 ID 찾기: Sleeper 웹 앱에서 리그를 여세요. URL에는 긴 숫자로 된 리그 ID가 포함되어 있습니다(예: sleeper.com/leagues/1234567890123456789/team).

사용자 ID 찾기: 브라우저에서 https://api.sleeper.app/v1/user/<your_sleeper_username>에 접속한 다음 user_id 필드를 복사하세요.

환경 변수

구성은 src/config.js에서 한 번만 읽습니다. 코드베이스의 그 어디에서도 process.env에 직접 접근하지 않습니다. 세 가지 모두 필요하며, 서버는 이 값들이 없으면 시작하지 않습니다.

.env.example을 .env로 복사하고 실제 값을 입력하세요:

cp .env.example .env

강력한 MCP_AUTH_TOKEN을 생성하세요:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

.env는 git에서 무시됩니다 — 실제 값을 절대 커밋하지 마세요. .env.example에는 항상 자리 표시자만 들어 있습니다.

인증

/mcp에 대한 모든 요청에는 다음이 포함되어야 합니다:

Authorization: Bearer <MCP_AUTH_TOKEN>

토큰이 없거나 올바르지 않으면 MCP 또는 Sleeper 로직이 실행되기 전에 401이 반환됩니다(src/auth.js에서 상수 시간 비교로 확인). 서버에는 다른 접근 제어가 없으므로, 이 인증이 리그 데이터와 공개 인터넷 사이에 있는 유일한 보호막입니다 — MCP_AUTH_TOKEN을 비밀번호처럼 취급하고 공유하거나 커밋하지 마세요.

/health는 의도적으로 인증을 요구하지 않습니다(리그 데이터가 없는 단순 liveness 확인입니다). Railway의 헬스 체크가 자유롭게 접근할 수 있도록 하기 위함입니다.

로컬 실행

npm install
cp .env.example .env   # then fill in real values
npm start               # or: npm run dev (auto-restarts on changes)

서버는 http://localhost:3000(또는 설정된 경우 $PORT)에서 수신 대기합니다.

curl로 간단한 스모크 테스트:

# health check (no auth)
curl http://localhost:3000/health

# MCP initialize (replace the token with your MCP_AUTH_TOKEN)
curl -s http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <your MCP_AUTH_TOKEN>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

# call the tool
curl -s http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <your MCP_AUTH_TOKEN>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_league_settings","arguments":{}}}'

Authorization 헤더가 없거나 잘못된 토큰을 사용한 요청은 401을 받아야 합니다.

클라이언트 연결

이 서버는 Streamable HTTP 전송 방식(stdio가 아닌 단일 /mcp 엔드포인트)을 사용합니다. 따라서 원격 또는 사용자 지정 MCP 커넥터를 추가하는 각 클라이언트의 안내에 따라, 배포된 URL과 Bearer 토큰을 가리키는 원격 MCP 서버로 추가됩니다. Authorization: Bearer <MCP_AUTH_TOKEN> 헤더를 해당 클라이언트가 요구하는 방식으로 구성하고, https://<your-railway-domain>/mcp를 가리키게 하세요.

Railway에 배포하기

1. 이 저장소를 GitHub에 푸시하세요(저장소에서 이 문서를 보고 있다면 이미 완료된 것입니다).

2. Railway에서 새 프로젝트를 만들고(또는 기존 프로젝트를 사용) 해당 GitHub 저장소에서 서비스를 추가하세요.

3. Railway는 Node.js를 자동으로 감지하여 npm install 후 npm start를 실행합니다. 이 설정에는 Procfile이나 Dockerfile이 필요 없습니다.

4. 서비스의 Variables 탭에서 SLEEPER_LEAGUE_ID, SLEEPER_USER_ID, MCP_AUTH_TOKEN을 설정하세요(로컬 개발 토큰과 다른 강한 강물 값을 사용). PORT는 설정하지 마세요 — Railway가 자동으로 주입합니다.

5. 중요 — PORT: Railway는 런타임에 PORT 환경 변수를 통해 컨테이너의 수신 대기 포트를 동적으로 지정합니다. 이 값은 고정되어 있지 않고 사전에 알 수도 없습니다. src/server.js는 process.env.PORT를 읽으며(src/config.js를 통해), 값이 설정되어 있지 않을 때만 3000을 폴백하고 이는 로컬 개발에서만 발생합니다. 포트를 하드코딩하지 마세요 — 하드코딩된 포트는 Railway에서 트래픽을 받을 수 없습니다.

6. 배포하세요. Railway는 https://<service>.up.railway.app과 같은 공개 도메인을 제공합니다. 당신의 MCP 엔드포인트는 https://<service>.up.railway.app/mcp입니다.

7. 위와 동일한 curl 명령으로 localhost:3000을 Railway 도메인으로 바꿔 검증한 다음, Claude Desktop / 모바일을 MCP_AUTH_TOKEN과 함께 그 URL로 연결하세요.

제한 사항

• 읽기 전용 — Sleeper 리그의 어떤 것도 수정할 수 없습니다.

• 배포당 단일 리그(SLEEPER_LEAGUE_ID는 도구 인자(config argument)가 아닌 구성 설정의 단일 값입니다).

• 무상태(stateless) 요청 처리 — 각 MCP 요청이 고유한 전송을 생성하므로 Railway 재시작 시 잃을 서버 사이드 세션 상태는 없지만, 요청 간 이어받을 수 있는 스트리밍도 없습니다.

• 지금까지는 get_league_settings만 구현되어 있습니다.

라이선스

MIT