Sleeper Fantasy Football MCP Server

A remote MCP (Model Context Protocol) server that wraps the Sleeper fantasy football public API. It runs as an HTTP service (Streamable HTTP transport) so it can be reached from Claude Desktop and the Claude mobile app over the internet — useful for pulling league data mid-draft from your phone.

Sleeper's API (https://api.sleeper.app/v1/, 文档) is public and read-only, so this server never touches any league settings, rosters, or picks — it only reads.

状态

This is the initial scaffold: one tool, get_league_settings, working end to end over Streamable HTTP with bearer token auth. More tools (rosters, matchups, draft picks, etc.) will follow the same pattern in 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

Adding a new tool means: add a fetch function to sleeperClient.js, register a tool in tools.js that calls it. server.js and auth.js don't need to change.

前提条件

• 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 故意不加认证（只是一个不涉及联盟数据的存活检查），以便 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 传输（一个单独的 /mcp 端点，而不是 stdio），因此，请按照每个客户端自身关于添加远程/自定义 MCP 连接器的说明，将它添加为远程 MCP 服务器，并指向你已部署的 URL 和 bearer 令牌。将客户端指向 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 在运行时通过 PORT 环境变量动态分配容器的监听端口；它不是固定的，也无法提前得知。src/server.js（通过 src/config.js）读取 process.env.PORT，只在未设置时才回退到 3000，而这只发生在本地开发中。永远不要硬编码端口——在 Railway 上硬编码的端口不会收到流量。

6. 部署。Railway 会提供一个类似 https://<service>.up.railway.app 的公共域名。你的 MCP 端点是 https://<service>.up.railway.app/mcp。

7. 用与上面相同的 curl 命令验证，将 localhost:3000 替换为你的 Railway 域名，然后用你的 MCP_AUTH_TOKEN 将 Claude Desktop / mobile 指向该 URL。

限制

• 只读——此服务器无法修改你 Sleeper 联盟中的任何内容。

• 每次部署只支持一个联盟（SLEEPER_LEAGUE_ID 是配置中的一个值，不是一个参数）。

• 无状态请求处理——每个 MCP 请求都会创建自己的 transport，因此 Railway 重启时不会丢失任何服务端会话状态，但也不能跨请求续传。

• 目前只实现了 get_league_settings。

License

MIT