Yahoo Fantasy Football → ChatGPT MCP bridge (read-only)

This starter connects:

ChatGPT → OpenAI Secure MCP Tunnel → this local MCP server → Yahoo Fantasy Sports API

Yahoo credentials and refresh tokens remain on your computer. Every exposed MCP tool performs a GET; there are no lineup, waiver, trade, draft, or roster-changing actions.

0. Confirm ChatGPT eligibility

As of August 30, 2026:

• ChatGPT Pro can connect custom MCPs with read/fetch permissions in developer mode.

• ChatGPT Business, Enterprise, and Edu support developer mode and full MCP; this starter remains read-only.

• Custom MCP apps are available in ChatGPT on the web, not mobile.

• If you only have Free, Go, or Plus and do not see developer mode, direct custom-MCP connection is not currently available on that plan.

Related MCP server: Yahoo Fantasy MCP

1. Install Python

Install Python 3.10 or later. Then open Terminal (macOS/Linux) or PowerShell (Windows) in this folder.

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Windows PowerShell

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

2. Apply for Yahoo Fantasy Sports API access and obtain OAuth credentials

Yahoo's current Fantasy Sports Developer Portal reviews applications before granting access. The access page says the API currently provides read-only access, which matches this bridge.

1. Review YAHOO_APPLICATION_DRAFT.md and edit it so every statement is truthful.

2. Apply at https://sports.yahoo.com/developer/access/. Clearly identify this as a personal or single-user, local, non-commercial, read-only tool.

3. The form requires a real website or app-details URL. Use a project page or repository you actually control; do not submit a fake URL.

4. Existing Yahoo Developer Network users can provide an existing Client ID in the application. New users can leave that field blank; Yahoo's form says access can be provisioned after approval.

5. After Yahoo approves the application, follow its instructions to obtain a Client ID (Consumer Key) and Client Secret (Consumer Secret), with private Fantasy Sports read access.

6. If the registration screen asks for an application type, use Installed Application for this personal stand-alone bridge. Use oob (out of band) as the redirect URI/callback when permitted. If a callback value causes invalid_grant, Yahoo's OAuth troubleshooting guide recommends leaving the callback blank for an installed application.

Approval is controlled by Yahoo and may not be immediate. The remaining setup can be prepared before approval, but the authorization and smoke-test steps require working Yahoo credentials.

Never send the Client ID, Client Secret, your Yahoo password, authorization code, or generated token file to ChatGPT or anyone else.

3. Configure this project

Copy the example environment file:

macOS / Linux

cp .env.example .env

Windows PowerShell

Copy-Item .env.example .env

Open .env and replace:

YAHOO_CLIENT_ID=replace_me
YAHOO_CLIENT_SECRET=replace_me

Leave YAHOO_REDIRECT_URI=oob unless your Yahoo app uses a different redirect URI.

4. Authorize Yahoo

With the virtual environment active:

python authorize_yahoo.py

A Yahoo page should open. Sign in on Yahoo, approve access, copy the one-time code, and paste it into the terminal. The script stores .yahoo_token.json locally and automatically refreshes expiring access tokens.

5. Test Yahoo access

python smoke_test.py

A successful result contains Yahoo fantasy_content data and normally includes your NFL team and league keys. League keys resemble 449.l.12345; team keys resemble 449.l.12345.t.1.

Run local unit tests too:

python -m unittest discover -s tests -v

6. Inspect the MCP tools locally

The current MCP Python SDK includes an Inspector launcher:

mcp dev server.py

Or launch the Inspector yourself:

npx @modelcontextprotocol/inspector@latest

Call list_my_football_teams first. Then test get_league_snapshot with a discovered league_key and get_team_roster with a discovered team_key.

7. Create an OpenAI Secure MCP Tunnel

ChatGPT cannot call a local MCP process directly. Secure MCP Tunnel creates an outbound-only route while leaving this server and its Yahoo secrets private.

1. Open the OpenAI Platform tunnel settings in the same personal Platform organization associated with your ChatGPT account/workspace.

2. Create a tunnel, associate it with the target ChatGPT workspace, and note its tunnel_id.

3. Create or obtain a runtime API key for tunnel-client. Do not put this key in .env and do not share it.

4. Download the current tunnel-client from Platform tunnel settings.

5. Print the exact local command for this project:

python print_tunnel_command.py

6. Use that output as the value of --mcp-command below.

macOS / Linux example

export CONTROL_PLANE_API_KEY="sk-REPLACE_ME"

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile yahoo-fantasy \
  --tunnel-id tunnel_REPLACE_ME \
  --mcp-command "/absolute/path/to/.venv/bin/python /absolute/path/to/server.py"

tunnel-client doctor --profile yahoo-fantasy --explain
tunnel-client run --profile yahoo-fantasy

Windows PowerShell example

$env:CONTROL_PLANE_API_KEY="sk-REPLACE_ME"

tunnel-client init `
  --sample sample_mcp_stdio_local `
  --profile yahoo-fantasy `
  --tunnel-id tunnel_REPLACE_ME `
  --mcp-command '"C:\absolute\path\.venv\Scripts\python.exe" "C:\absolute\path\server.py"'

tunnel-client doctor --profile yahoo-fantasy --explain
tunnel-client run --profile yahoo-fantasy

Keep tunnel-client run --profile yahoo-fantasy running whenever ChatGPT needs live Yahoo data. For an always-on setup later, run it on a trusted home server or private VM and protect the Yahoo credential files.

8. Add the MCP app in ChatGPT

Use ChatGPT on the web:

1. Enable Developer mode under the Apps/Advanced Settings area available to your plan/workspace.

2. Open the custom app/plugin creation screen and create a developer-mode app.

3. Choose Tunnel as the connection type.

4. Select the tunnel or paste its tunnel_id.

5. Choose no additional MCP authentication for this personal bridge; Yahoo authentication is handled locally by the server.

6. Scan the tools. Confirm that every tool is labeled/read as non-destructive and read-only.

7. Create/enable the app.

If the tunnel does not appear, check that it is associated with the target ChatGPT workspace and that the relevant Platform account has Tunnels Read + Use permission.

9. First prompts to use in ChatGPT

Use my Yahoo Fantasy app. List my football teams and identify every league_key and team_key.

Use Yahoo Fantasy to pull my league settings, standings, teams, this week's scoreboard, and my roster. Explain the scoring format and identify my three biggest roster weaknesses.

Using my Yahoo league settings and current roster, review available RBs and WRs, recent transactions, and this week's matchup. Rank five waiver targets and recommend FAAB percentages. Do not make any roster changes.

Included read-only tools

• list_my_football_teams

• list_my_football_leagues

• get_league_metadata

• get_league_settings

• get_league_standings

• get_league_teams

• get_league_scoreboard

• get_league_snapshot

• get_team_roster

• get_league_draft_results

• get_recent_transactions

• get_available_players

• get_player_metadata

• get_player_stats

• read_yahoo_fantasy_path (strict, GET-only escape hatch)

Troubleshooting

invalid_grant during Yahoo authorization

Confirm the redirect URI matches exactly. For a personal stand-alone app, use Installed Application and oob; Yahoo's troubleshooting documentation also says a callback value can cause this error and recommends an empty callback in that situation. Recreate the app if necessary.

Yahoo password changed

Yahoo says password changes revoke refresh tokens. Run python authorize_yahoo.py again.

Tool scan works, but calls fail

Run these in order:

python smoke_test.py
tunnel-client doctor --profile yahoo-fantasy --explain
tunnel-client run --profile yahoo-fantasy

Yahoo returns XML

The client requests JSON but includes a built-in XML-to-dictionary fallback because portions of the Yahoo Fantasy API are legacy.

A Yahoo endpoint is not covered

Use read_yahoo_fantasy_path with a documented relative Fantasy API path. It blocks full URLs, query strings, path traversal, and non-Fantasy prefixes, and the client still performs only GET requests.

Security checklist

• Use Yahoo Fantasy Read, not Read/Write.

• Never commit .env or .yahoo_token.json; both are in .gitignore.

• Never paste Yahoo or OpenAI secrets into ChatGPT.

• Keep the project on a trusted computer.

• Review MCP tool names, descriptions, schemas, and annotations before enabling the app.

• Keep the attribution “Fantasy data provided by Yahoo Fantasy” whenever Yahoo data is displayed; the server includes it in every tool result.

• Revoke the Yahoo app from Yahoo account settings if the computer or token file is compromised.