Sleeper Fantasy Football MCP Server

Удалённый MCP-сервер (Model Context Protocol), оборачивающий публичный API фэнтези-футбола Sleeper. Он работает как HTTP-сервис (транспорт Streamable HTTP), поэтому до него можно добраться из Claude Desktop и мобильного приложения Claude через интернет — это удобно, когда хочется получить данные лиги прямо с телефона посреди драфта.

API Sleeper (https://api.sleeper.app/v1/, документация) — публичный и только для чтения, поэтому этот сервер никогда не изменяет ни настройки лиги, ни ростера, ни пики — он только читает.

Статус

Это начальная заготовка: один инструмент, get_league_settings, работающий на протяжении всей цепочки через Streamable HTTP с аутентификацией через bearer-токен. Остальные инструменты (rosters, matchups, draft picks и т.д.) появятся по той же схеме в 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

Добавить новый инструмент — значит: добавить fetch-функцию в sleeperClient.js и зарегистрировать инструмент в tools.js, который её вызывает. server.js и auth.js менять не нужно.

Предварительные требования

• Node.js 24.16.0 (зафиксирована в package.json в секции engines)

• ID лиги Sleeper и ID пользователя Sleeper

Как найти 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>

Отсутствующий или неверный токен возвращает 401 до того, как выполняется любая логика MCP или Sleeper (src/auth.js, сравнение с постоянным временем). Это единственный барьер между данными вашей лиги и открытым интернетом; другой системы контроля доступа у сервера нет — относитесь к MCP_AUTH_TOKEN как к паролю и не распространяйте его и не коммитьте.

/health намеренно доступен без аутентификации (это просто проверка живости, без данных лиги), чтобы health-чеки 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, если задан).

Быстрый smoke-тест с 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 (единая конечная точка /mcp, а не stdio), поэтому он добавляется как удалённый MCP-сервер со своим развёрнутым URL и bearer-токеном. Подключайте его по инструкциям вашего клиента для добавления удалённого/пользовательского MCP-коннектора, указывая https://<your-railway-domain>/mcp и подставляя заголовок Authorization: Bearer <MCP_AUTH_TOKEN> так, как этого требует клиент.

Деплой на 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 продynamicчески присваивает контейнеру порт прослушивания через переменную окружения PORT во время выполнения; он не фиксирован и заранее неизвестен. src/server.js читает process.env.PORT (через src/config.js) и переходит на 3000 только если PORT не установлен, а это бывает только в локальной разработке. Никогда не жёстко задавайте порт — порт, заданный вручную, не будет получать трафик на Railway.

6. Выполните деплой. Railway выдаст публичный домен вида https://<сервис>.up.railway.app. Ваш MCP-эндпоинт — https://<service>.up.railway.app/mcp.

7. Проверьте тем же curl-командам, что и выше, заменив localhost:3000 на свой домен Railway, а затем укажите Claude Desktop / мобильному приложению этот URL и MCP_AUTH_TOKEN.

Ограничения

• Только чтение — этот сервер не может ничего изменять в вашей лиги Sleeper.

• Одна лига на деплой (SLEEPER_LEAGUE_ID — это одно значение в конфигурации, а не аргумент инструмента).

• Обработка запросов без состояния — каждый MCP-запрос создаёт собственный транспорт, поэтому при перезапуске Railway не происходит потери состояния серверной сессии, но и возобновляемой потоковой передачи между запросами тоже нет.

• Пока реализованы только get_league_settings.

Лицензии

MIT