# LiveFPL MCP Server

An [MCP](https://modelcontextprotocol.io) server that exposes **Fantasy Premier
League player price rise/fall predictions** from [LiveFPL](https://www.livefpl.net/prices).

The data is served from LiveFPL's public JSON host (`https://livefpl.us`) — the
same endpoints the website itself loads. No account, API key, or authentication
is required.

## Data source (reverse-engineered)

The `https://www.livefpl.net/prices` page loads its price-prediction table from:

| Endpoint | Purpose |
| --- | --- |
| `GET https://livefpl.us/api/prices.json` | Per-player price-change progress & predictions |
| `GET https://livefpl.us/top_transfers.json` | Most common transfer pairs (in/out) |
| `GET https://livefpl.us/version.json` | Gameweek / countdown metadata |
| `GET https://plan.livefpl.net/leagues/{id}` | **League live-score table** (server-rendered HTML, parsed) |

The league page is **server-rendered HTML** (no JSON API) — the live gameweek
standings are baked into the page, so the server fetches and parses that HTML.

### `prices.json` fields

Keyed by player id. For each player:

- `progress` — current progress toward a price change, as a fraction of the
  threshold. **Positive ⇒ rising, negative ⇒ falling.** `+1.0` means a rise is
  due; `-1.0` means a fall is due. Shown on the site as the **"Now"** column.
- `progress_tonight` — predicted progress by the next change cutoff. Shown as the
  **"Prediction"** column. This is what the tools sort on.
- `per_hour` — rate of change of progress per hour ("Per hr" column).
- `cost`, `name`, `team`, `type` (GK/DEF/MID/FW).

## Tools

| Tool | Description |
| --- | --- |
| `livefpl_price_risers` | Players most likely to **rise**, sorted by predicted progress. Filters: `limit`, `position`, `team`, `threshold`. |
| `livefpl_price_fallers` | Players most likely to **fall**. Same filters. |
| `livefpl_player_prediction` | Price prediction for a specific player by `name` (partial match). |
| `livefpl_top_transfers` | Most common transfer pairs (player in/out) driving price changes. |
| `livefpl_price_status` | Metadata for the current price-change window / gameweek. |
| `livefpl_transfer_trend_graph` | Transfer trend as a **node-link graph image (PNG)** — circle size = volume, arrows out → in. Params: `top_n`, `color_by` (`"direction"` for net in/out, or `"position"` for GK/DEF/MID/FW colours). |
| `livefpl_transfer_trend_by_position` | **2×2 grid image (PNG)** with one transfer-trend graph per position (GK, DEF, MID, FW). Param: `top_n` (default 40). |
| `livefpl_transfer_trend_data` | Same transfer-trend data as **JSON** (per-player net + pair edges, incl. position/team/cost). Param: `top_n`. |
| `livefpl_league_live_score` | **Live gameweek standings** for a classic league. Params: `league_id`, `limit`. Returns rank (+movement), team/manager, live GW score, total, captain/vice, chip, FT, team value, players played. |

The transfer-trend graph is derived client-side from `top_transfers.json` (the
same way the LiveFPL page builds its bubble chart): per-player net = transfers in
− transfers out, node size = total volume, edges = transfer pairs (out → in).

Each player result includes `progress_now_pct`, `prediction_pct`, `per_hour_pct`,
`direction` (`rise`/`fall`/`stable`) and `predicted_new_cost`.

## Install

```bash
cd livefpl-mcp
uv sync
```

## Run

```bash
uv run livefpl-mcp
```

The server speaks MCP over stdio.

## Claude Desktop / MCP client config

Add to your MCP client configuration (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "livefpl": {
      "command": "uv",
      "args": ["--directory", "C:\\path-to-mcp\\livefpl-mcp", "run", "livefpl-mcp"]
    }
  }
}
```

## Example prompts

- "Which FPL defenders are about to rise in price?"
- "Show me the top 10 price fallers tonight."
- "What's the price prediction for Haaland?"
- "What are the most popular transfers right now?"
- "Show the live scores for league 230412."
- "Who's winning gameweek in my league 230412 right now?"

## Notes

- Predictions are LiveFPL's, not the official FPL algorithm; accuracy is best on
  single gameweeks (LiveFPL notes double-gameweek rules are less certain).
- Data is fetched live on each tool call.

## License

MIT