Sleeper Fantasy Football MCP Server

Ein Remote-MCP-Server (Model Context Protocol), der die öffentliche Fantasy-Football-API von Sleeper kapselt. Er läuft als HTTP-Dienst (Streamable-HTTP-Transport) und ist so über das Internet von Claude Desktop und der Claude mobile app erreichbar — nützlich, um mitten im Draft Ligadaten vom Handy abzurufen.

Die API von Sleeper (https://api.sleeper.app/v1/, Doku) ist öffentlich und schreibgeschützt, daher fasst dieser Server nie Ligaeinstellungen, Aufstellungen oder Draft-Picks an — er liest nur.

Status

Das ist das erste Grundgerüst: ein Tool, get_league_settings, das end-to-end über Streamable HTTP mit Bearer-Token-Authentifizierung funktioniert. Weitere Tools (Rosters, Matchups, Draft-Picks usw.) werden demselben Muster in src/tools.js folgen.

Related MCP server: Yahoo Fantasy Baseball MCP Server

Projektstruktur

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

Ein neues Tool hinzuzufügen bedeutet: eine Fetch-Funktion in sleeperClient.js ergänzen, ein Tool in tools.js registrieren, das sie aufruft. server.js und auth.js müssen nicht geändert werden.

Voraussetzungen

• Node.js 24.16.0 (festgelegt in package.json unter engines)

• Eine Sleeper-Liga-ID und eine Benutzer-ID

So finden Sie Ihre Liga-ID: Öffnen Sie Ihre Liga in der Sleeper-Web-App — die URL enthält eine lange numerische Liga-ID (z. B. sleeper.com/leagues/1234567890123456789/team).

So finden Sie Ihre Benutzer-ID: Besuchen Sie https://api.sleeper.app/v1/user/<your_sleeper_username> in einem Browser und kopieren Sie das Feld user_id.

Umgebungsvariablen

Die Konfiguration wird einmal in src/config.js gelesen — nichts anderes im Codebestand greift direkt auf process.env zu. Alle drei sind erforderlich; der Server startet ohne sie nicht.

Kopieren Sie .env.example nach .env und tragen Sie echte Werte ein:

cp .env.example .env

Erzeugen Sie ein starkes MCP_AUTH_TOKEN:

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

.env ist per .gitignore ausgeschlossen — committen Sie niemals echte Werte. .env.example enthält nur Platzhalter.

Auth

Jede Anfrage an /mcp muss Folgendes enthalten:

Authorization: Bearer <MCP_AUTH_TOKEN>

Fehlende oder falsche Tokens erhalten eine 401, bevor irgendeine MCP- oder Sleeper-Logik läuft (src/auth.js, Vergleich mit einer Prüfung in konstanter Zeit). Das ist die einzige Barriere zwischen Ihren Liga-Daten und dem offenen Internet, da der Server keinerlei andere Zugriffskontrolle hat — behandeln Sie MCP_AUTH_TOKEN wie ein Passwort, teilen Sie es nicht und committen Sie es nicht.

/health ist bewusst nicht authentifiziert (nur ein Bereitschaftstest, der keine Liga-Daten preisgibt), damit Railway-Health-Checks ungehindert darauf zugreifen können.

Lokal ausführen

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

Der Server lauscht auf http://localhost:3000 (oder auf $PORT, falls gesetzt).

Kurzer Smoke-Test mit 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":{}}}'

Eine Anfrage ohne Authorization-Header oder mit falschem Token sollte eine 401 erhalten.

Client verbinden

Dieser Server verwendet den Streamable-HTTP-Transport (einen einzelnen /mcp-Endpunkt, kein stdio) und wird daher als Remote-MCP-Server hinzugefügt, der auf Ihre bereitgestellte URL und das Bearer-Token verweist — so wie es die jeweiligen Client-Anleitung für das Hinzufügen eines Remote-/Custom-MCP-Connectors beschreibt. Richten Sie ihn auf https://<your-railway-domain>/mcp mit dem Authorization: Bearer <MCP_AUTH_TOKEN>-Header ein, wie vom Client verlangt.

Deploying to Railway

1. Schieben Sie dieses Repository zu GitHub (bereits erledigt, wenn Sie das direkt aus dem Repository lesen).

2. Erstellen Sie in Railway ein neues Projekt (oder verwenden Sie ein vorhandenes) und fügen Sie einen Dienst aus diesem GitHub-Repository hinzu.

3. Railway erkennt Node.js automatisch und führt npm install und dann npm start aus. Für dieses Setup sind weder ein Procfile noch ein Dockerfile erforderlich.

4. Legen Sie im Tab Variablen des Dienstes SLEEPER_LEAGUE_ID, SLEEPER_USER_ID und MCP_AUTH_TOKEN fest (verwenden Sie einen anderen, starken Wert als ein lokales Dev-Token). Setzen Sie kein PORT — Railway fügt ihn automatisch ein.

5. Wichtig — PORT: Railway weist der Lauschport des Containers zur Laufzeit dynamisch über die Umgebungsvariable PORT zu; er ist nicht festgelegt und nicht im Voraus bekannt. src/server.js liest process.env.PORT (via src/config.js) und fällt nur auf 3000 zurück, wenn die Variable nicht gesetzt ist — das passiert nur in der lokalen Entwicklung. Hardcodieren Sie niemals einen Port – ein hartkodierter Port wird bei Railway keinen Datenverkehr erhalten.

6. Deployen Sie. Railway stellt Ihnen eine öffentliche Domain wie https://<service>.up.railway.app bereit. Ihr MCP-Endpunkt ist https://<service>.up.railway.app/mcp.

7. Überprüfen Sie dies mit denselben curl-Befehlen wie oben, ersetzen Sie localhost:3000 durch Ihre Railway-Domain und richten Sie dann Claude Desktop / mobile auf dieser URL mit Ihrem MCP_AUTH_TOKEN ein.

Einschränkungen

• Schreibgeschützt – das kann nichts in Ihrer Sleeper-Liga ändern.

• Eine Liga pro Bereitstellung (SLEEPER_LEAGUE_ID ist ein Wert in der Konfiguration, kein Tool-Argument).

• Zustandslose Anforderungsverarbeitung – jede MCP-Anfrage startet einen eigenen Transport, sodass es keinen serverseitigen Sitzungszustand gibt, der bei einem Railway-Neustart verloren gehen könnte, aber auch kein Rückstauschamberübergreifendes Streaming über Anfragen hinweg gibt.

• Bisher ist nur get_league_settings implementiert.

Lizenz

MIT