Sleeper Fantasy Football MCP Server

Un servidor MCP (Model Context Protocol) remoto que envuelve la API pública de fútbol de fantasía de Sleeper. Se ejecuta como un servicio HTTP (transporte Streamable HTTP) para que se pueda acceder a él desde Claude Desktop y la aplicación móvil de Claude a través de internet — útil para consultar datos de la liga a mitad de draft desde tu teléfono.

La API de Sleeper (https://api.sleeper.app/v1/, documentación) es pública y de solo lectura, por lo que este servidor nunca toca la configuración de la liga, las plantillas ni las selecciones — solo lee.

Estado

Este es el esqueleto inicial: una herramienta, get_league_settings, que funciona de extremo a extremo mediante Streamable HTTP con autenticación de token Bearer. Más herramientas (plantillas, enfrentamientos, selecciones de draft, etc.) seguirán el mismo patrón en src/tools.js.

Related MCP server: Yahoo Fantasy Baseball MCP Server

Estructura del proyecto

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

Añadir una nueva herramienta significa: añade una función fetch a sleeperClient.js, registra una herramienta en tools.js que la llame. server.js y auth.js no necesitan cambios.

Requisitos previos

• Node.js 24.16.0 (fijado en package.json bajo engines)

• Un ID de liga y un ID de usuario de Sleeper

Cómo encontrar tu ID de liga: abre tu liga en la aplicación web de Sleeper — la URL contiene un ID numérico largo (p. ej. sleeper.com/leagues/1234567890123456789/team).

Cómo encontrar tu ID de usuario: visita https://api.sleeper.app/v1/user/<your_sleeper_username> en un navegador y copia el campo user_id.

Variables de entorno

La configuración se lee una vez en src/config.js — nada más en el código base toca process.env directamente. Las tres son obligatorias; el servidor se niega a arrancar sin ellas.

Copia .env.example a .env y rellena los valores reales:

cp .env.example .env

Genera un MCP_AUTH_TOKEN seguro:

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

.env está ignorado por git — nunca hagas commit de valores reales. .env.example solo contiene marcadores de posición.

Autenticación

Cada solicitud a /mcp debe incluir:

Authorization: Bearer <MCP_AUTH_TOKEN>

Los tokens ausentes o incorrectos reciben un 401 antes de que se ejecute ninguna lógica de MCP o de Sleeper (src/auth.js, con comparación en tiempo constante). Esto es lo único que se interpone entre los datos de tu liga y el internet abierto, ya que el servidor no tiene otro control de acceso — trata MCP_AUTH_TOKEN como una contraseña y no lo compartas ni lo guardes en el repositorio.

/health está intencionalmente sin autenticación (solo una comprobación de estado sin datos de liga) para que las comprobaciones de Railway puedan acceder libremente.

Ejecutar localmente

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

El servidor escucha en http://localhost:3000 (o en $PORT si está configurado).

Prueba de humo rápida con 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":{}}}'

Una solicitud sin cabecera Authorization, o con el token incorrecto, debería devolver 401.

Conectar un cliente

Este servidor usa el transporte Streamable HTTP (un único endpoint /mcp, no stdio), por lo que se añade como servidor MCP remoto apuntando a tu URL desplegada más el token Bearer, según las instrucciones propias de cada cliente para añadir un conector MCP remoto/personalizado. Apúntalo a https://<your-railway-domain>/mcp con la cabecera Authorization: Bearer <MCP_AUTH_TOKEN> configurada según lo que requiera ese cliente.

Despliegue en Railway

t>1. Sube este repositorio a GitHub (ya está hecho si estás leyendo esto desde el repositorio). 2. En Railway, crea un proyecto nuevo (o usa uno existente) y añade un servicio desde ese repositorio de GitHub. 3. Railway detecta Node.js automáticamente y ejecuta npm install y luego npm start. No se necesitan Procfile ni Dockerfile para esta configuración. 4. En la pestaña Variables del servicio, configura SLEEPER_LEAGUE_ID, SLEEPER_USER_ID y MCP_AUTH_TOKEN (usa un valor fuerte y distinto de cualquier token local de desarrollo). No definas PORT — Railway lo inyecta automáticamente. 5. Importante — PORT: Railway asigna de forma dinámica el puerto de escucha del contenedor a través de la variable de entorno PORT en tiempo de ejecución; no es fijo ni se puede conocer de antemano. src/server.js lee process.env.PORT (a través de src/config.js) y utiliza 3000 como valor por defecto solo cuando no está definido, lo que ocurre únicamente en el desarrollo local. Nunca fijes un puerto en el código — un puerto fijo no recibirá tráfico en Railway. 6. Despliega. Railway te dará un dominio público como https://<service>.up.railway.app. Tu endpoint MCP es https://<service>.up.railway.app/mcp. 7. Verifícalo con los mismos comandos curl de arriba, cambiando localhost:3000 por tu dominio de Railway, y luego apunta Claude Desktop / la aplicación móvil a esa URL con tu MCP_AUTH_TOKEN.

Limitaciones

• Solo lectura — esto no puede modificar nada en tu liga de Sleeper.

• Una sola liga por despliegue (SLEEPER_LEAGUE_ID es un valor en la configuración, no un argumento de herramienta).

• Manejo de solicitudes sin estado — cada solicitud MCP pone en marcha su propio transporte, por lo que no hay estado de sesión del lado del servidor que se pueda perder al reiniciar Railway, pero tampoco hay streaming reanudable entre solicitudes.

• Solo se ha implementado get_league_settings por ahora.

Licencia

MIT