# 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.

## 1. Install Python

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

### macOS / Linux

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

### Windows PowerShell

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

```bash
cp .env.example .env
```

### Windows PowerShell

```powershell
Copy-Item .env.example .env
```

Open `.env` and replace:

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

```bash
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

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

```bash
python -m unittest discover -s tests -v
```

## 6. Inspect the MCP tools locally

The current MCP Python SDK includes an Inspector launcher:

```bash
mcp dev server.py
```

Or launch the Inspector yourself:

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

```bash
python print_tunnel_command.py
```

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

### macOS / Linux example

```bash
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

```powershell
$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

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

```text
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.
```

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

```bash
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.