fantasy-football-mcp-public
Yahoo Fantasy Football MCP server for Claude Desktop - Advanced lineup optimization, draft assistance, and league management. Built using Claude Code.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/derekrbreese--fantasy-football-mcp-public)HTML
<a href="/listings/derekrbreese--fantasy-football-mcp-public"><img src="/api/listings/derekrbreese--fantasy-football-mcp-public/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
git clone https://github.com/derekrbreese/fantasy-football-mcp-public.git cd fantasy-football-mcp-public pip install -r requirements.txt
Copy `.env.example` to `.env` and provide your Yahoo developer credentials. Do not commit `.env`, Yahoo token JSON files, OAuth state, refresh tokens, or other authentication artifacts.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 147 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Fantasy Football MCP Server
- A personal, single-user Model Context Protocol (MCP) server for Yahoo Fantasy Football. It exposes league, roster, matchup, waiver-wire, draft, and lineup-analysis data to AI clients while keeping the underlying fantasy data source separate from the model.
- ## Current status
- This project is built and run as a **single-user app**: you supply your own Yahoo developer credentials and tokens, and the server serves your leagues to your MCP client. It is not intended to be deployed by someone else as a shared, multi-user service.
- Experimental hosted, multi-user development lives on the [`multi-user-app` branch](https://github.com/derekrbreese/fantasy-football-mcp-public/tree/multi-user-app). See its [roadmap](https://github.com/derekrbreese/fantasy-football-mcp-public/blob/multi-user-app/docs/MULTI_USER_ROADMAP.md) for planned work toward a possible ChatGPT app. That branch is not a ready-to-deploy shared service; use `main` for personal use.
- Note that Yahoo Fantasy Sports API access now requires manual approval from Yahoo, and Yahoo currently provides read access only. Write actions such as adding/dropping players or changing lineups are therefore not part of the tool surface.
- ## Core capabilities
- - Multi-league Yahoo fantasy football discovery
- - League settings and standings
- - Team rosters and weekly matchups
- - Free-agent and waiver-wire research
- - Team comparisons
- - Draft rankings, recommendations, and draft-state analysis
- - Lineup optimization
- - Optional external player-context/enrichment integrations
- ## MCP tools
- The main FastMCP server currently exposes:
- - `ff_get_leagues`
- - `ff_get_league_info`
- - `ff_get_standings`
- - `ff_get_roster`
- - `ff_get_matchup`
- - `ff_get_players`
- - `ff_compare_teams`
- - `ff_build_lineup`
- - `ff_get_draft_results`
- - `ff_get_waiver_wire`
- - `ff_get_draft_rankings`
- - `ff_get_draft_recommendation`
- - `ff_analyze_draft_state`
- - `ff_analyze_reddit_sentiment`
- The server also contains maintenance tools used for local operation and troubleshooting.
- ## Installation
- ```bash
- git clone https://github.com/derekrbreese/fantasy-football-mcp-public.git
- cd fantasy-football-mcp-public
- pip install -r requirements.txt
- ```
- Copy `.env.example` to `.env` and provide your Yahoo developer credentials. Do not commit `.env`, Yahoo token JSON files, OAuth state, refresh tokens, or other authentication artifacts.
- ## Yahoo API access
- Create the Yahoo developer application as a **Web Application** ("Traditional web app"), not a native/installed app — only web apps are issued the client secret this server needs. See [INSTALLATION.md](INSTALLATION.md) for the full steps.
- Creating a Yahoo developer application is no longer sufficient by itself to use the Fantasy Sports API. Apply for Fantasy API access through Yahoo's developer access process and associate the approval with your existing client ID.
- Yahoo's current access model is read-only. This project therefore treats league-management recommendations separately from transaction execution.
- ## Authentication
- The server reads your Yahoo credentials from environment variables:
- ```env
- YAHOO_CLIENT_ID=...
- YAHOO_CLIENT_SECRET=...
- YAHOO_ACCESS_TOKEN=...
- YAHOO_REFRESH_TOKEN=...
- YAHOO_GUID=...
- ```
- This single-user mode is the supported way to run the app.
- ## Running the MCP server
- FastMCP HTTP server:
- ```bash
- python fastmcp_server.py
- ```
- By default the server listens on port 8000 locally. Cloud platforms can set `PORT`.
- Traditional stdio MCP entry point:
- ```bash
- python fantasy_football_multi_league.py
- ```
- Docker:
- ```bash
- docker build -t fantasy-football-mcp .
- docker run --env-file .env -p 8080:8080 fantasy-football-mcp
- ```
- Authentication files and token JSON files are explicitly excluded from the Docker build context.
- ## Testing
- ```bash
- pytest
- ```
- Credential-isolation tests cover request-scoped token handling and user-namespaced cache keys.
- ## Security notes
- Even as a single-user app, keep credentials out of the repository:
- - Never commit Yahoo access or refresh tokens.
- - Never bake your tokens into a container image.
- - Keep your Yahoo client secret server-side.
- - Rotate any credential that has ever been committed to a public Git history.
- If a secret was previously committed, deleting the current file is not sufficient by itself: revoke/rotate the credential and, when appropriate, rewrite the repository history.
- ## Project structure
- ```text
- fantasy-football-mcp-public/
- ├── fastmcp_server.py
- ├── fantasy_football_multi_league.py
- ├── lineup_optimizer.py
- ├── matchup_analyzer.py
- ├── position_normalizer.py
- ├── src/
- │ ├── api/
- │ │ ├── yahoo_client.py
- │ │ └── yahoo_credentials.py
- │ ├── agents/
- │ ├── handlers/
- │ ├── models/
- │ ├── services/
- │ └── strategies/
- ├── tests/
- ├── utils/
- ├── Dockerfile
- └── requirements.txt
- ```
- ## License
- See `LICENSE`.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.