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. See its roadmap 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

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 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:

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:

python fastmcp_server.py

By default the server listens on port 8000 locally. Cloud platforms can set PORT.

Traditional stdio MCP entry point:

python fantasy_football_multi_league.py

Docker:

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

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

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.