Fantasy Premier League (FPL)

fpl-mcp

An open-source MCP server for Fantasy Premier League that works with Claude, ChatGPT, Grok, Cursor, VS Code and any other MCP client. It pulls live data from the official FPL API and past seasons (2016-17 onward) from the vaastav dataset, predicts every player's points for the next five gameweeks, and recommends squads, transfers, captains and chips. Data lives in SQLite or Supabase.

Try it without installing anything:

• Remote URL: https://fpl-mcp-9tiv.onrender.com/mcp (claude.ai, ChatGPT, Grok, Cursor; see Connecting AI clients)
• npm: npx -y fpl-mcp-server for apps that run local servers (Claude Desktop, Cursor, VS Code)
• Smithery and the official MCP Registry (io.github.GilbertKamau/fpl-mcp)

The hosted server runs on a free plan, so the first request after a quiet spell can take a minute.

Example questions: *"Who are the best midfielders under £7m for the next 3 gameweeks?"*, *"Suggest transfers for team 1234567"*, *"Should I play my Bench Boost this week?"*

Setup

Requires Python 3.12+.

git clone https://github.com/GilbertKamau/fpl_mcp.git && cd fpl_mcp

python -m venv .venv

Windows: .venv\Scripts\activate macOS/Linux: source .venv/bin/activate

pip install -e ".[supabase,dev]" fpl-sync all # load data (~3 min to SQLite; ~15 min to a remote Supabase the first time) fpl-model all # train the model and write predictions (~3-6 min the first time)

fpl-sync jobs:

fpl-model jobs: evaluate (test only), compare (feature sets side by side), train, predict, all (train + predict). Add --refresh-cache after re-loading history, so the local cache of past seasons is rebuilt.

Database

SQLite at data/fpl.db by default. To use Supabase, copy .env.example to .env and paste your Supabase Session pooler connection string as DATABASE_URL (the direct db. .supabase.co host is IPv6-only). Special characters in the password are encoded automatically. Tables are created automatically.

Data quirks: 2019-20 gameweeks run to 47 (the COVID restart was numbered 39-47); 2024-25 includes AM (assistant manager) rows, which the model ignores; xG/xA exist from 2022-23 onward.

data/ (SQLite backup, cache, logs), models/ and .env are git-ignored, and a local pre-commit hook refuses to commit them.

Prediction model

LightGBM predicts each player's points per fixture from information available before kick-off:

• Form: rolling averages over the last 1, 3, 6, 12 and 38 matches (points, minutes, starts, xG, xA, bonus, BPS, ICT, defensive contributions...)
• Market: ownership and net transfers that gameweek, as percentiles (the crowd's read on fitness and form)
• Context: price, position, home/away, days since the last match
• Team strength: both clubs' recent goals and xG for and against

A gameweek's expected points is the sum over its fixtures, so double gameweeks count twice. Injury and suspension news scales the next gameweek's prediction by FPL's chance of playing. The trained model is stored in the database, so any machine can make predictions with it.

Testing on past seasons. Walk-forward: for each of the last three complete seasons, the model is trained only on earlier seasons and predicts every fixture. The baseline is the player's average points over their last 6 matches.

That is 7.5% better than the baseline overall. Adding last-match form, season-long form and the market features improved the average MAE from 0.982 to 0.958 and was better in every test season (fpl-model compare reruns this). A retrained model is only used if it beats the baseline and is no worse than the current model.

Past-season tests have no injury news (there's no historical record of it), so they understate live accuracy. They also can't fairly be compared with FPL's own expected points: the historical xP column includes injury news, and its 2025-26 values are on a different scale.

Live tracking. Every prediction is archived. After each gameweek, the prediction made before the deadline is scored against actual points, next to two benchmarks recorded at the same moment: the 6-match baseline and FPL's own expected points (ep_next). It also compares what each method's top 20 players actually scored. model_report shows the running results.

FPL points are very noisy (a 2-pointer and a 15-pointer can come from the same performance), so treat predictions as estimates.

Optimizer

Integer programs solved with HiGHS (via PuLP) that follow FPL rules: 2 GKP / 5 DEF / 5 MID / 3 FWD, max 3 per club, a valid formation, the budget, and −4 per transfer beyond the free ones. Points for later gameweeks are discounted (×0.85 per week) because predictions further out are less reliable.

For a manager's team it uses public endpoints only (no login). Selling prices are estimated from the manager's transfer history (FPL keeps half of any price rise), and free transfers from their gameweek history (up to 5 banked, kept through Wildcard and Free Hit weeks). Transfers made since the last deadline aren't public yet, so they aren't included.

MCP tools

Connecting AI clients

There are two ways to run the server:

• Local (stdio): your AI app starts the server on your computer. Works with Claude Code, Claude Desktop, Cursor and VS Code. Nothing is exposed to the internet.
• Remote (HTTP): you host the server at a public HTTPS URL (see Deploying). Required for claude.ai, ChatGPT and Grok, which can't start programs on your computer.

In the examples, /path/to/fpl_mcp/.venv/bin/python is the Python inside your virtual environment (Windows: C:\path\to\fpl_mcp\.venv\Scripts\python.exe), and https://your-server.example.com/mcp is your deployed URL.

Claude Code

claude mcp add fpl -- /path/to/fpl_mcp/.venv/bin/python -m fpl_mcp.server        # local

claude mcp add --transport http fpl https://your-server.example.com/mcp # remote

Claude Desktop

Local: Settings > Developer > Edit Config, then add to claude_desktop_config.json:

{

"mcpServers": { "fpl": { "command": "/path/to/fpl_mcp/.venv/bin/python", "args": ["-m", "fpl_mcp.server"] } } }

Remote: use Settings > Connectors > Add custom connector (same as claude.ai below).

claude.ai

Settings > Connectors > Add custom connector, and paste https://your-server.example.com/mcp. Available on paid plans; on Team/Enterprise an owner adds it for the organization. claude.ai connects to servers without a login or with OAuth, so leave MCP_AUTH_TOKEN unset.

ChatGPT

Turn on Developer mode (Settings > Apps & Connectors > Advanced), create a connector with the URL https://your-server.example.com/mcp and authentication None, then pick it from the tools menu in a chat. Plan availability varies, so check OpenAI's current docs. Like claude.ai, it can't send a fixed token, so leave MCP_AUTH_TOKEN unset.

Grok (xAI API)

Grok connects to remote MCP servers through the xAI API:

from xai_sdk import Client

from xai_sdk.chat import user from xai_sdk.tools import mcp

client = Client() # reads XAI_API_KEY chat = client.chat.create( model="grok-4.7", tools=[mcp(server_url="https://your-server.example.com/mcp", server_label="fpl")], ) chat.append(user("Who should I captain in gameweek 7?")) print(chat.sample().content)

Or with the Responses API, add this to tools:

{ "type": "mcp", "server_url": "https://your-server.example.com/mcp", "server_label": "fpl" }

If you set MCP_AUTH_TOKEN, also pass "authorization": " ".

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{

"mcpServers": { "fpl": { "command": "/path/to/fpl_mcp/.venv/bin/python", "args": ["-m", "fpl_mcp.server"] } } }

Remote: "fpl": { "url": "https://your-server.example.com/mcp" }, plus "headers": { "Authorization": "Bearer " } if you set a token.

VS Code (GitHub Copilot agent mode)

.vscode/mcp.json:

{

"servers": { "fpl": { "type": "stdio", "command": "/path/to/fpl_mcp/.venv/bin/python", "args": ["-m", "fpl_mcp.server"] } } }

Remote: "fpl": { "type": "http", "url": "https://your-server.example.com/mcp" }.

Anything else

Any MCP client that supports stdio or Streamable HTTP works. To try the server interactively: npx @modelcontextprotocol/inspector /path/to/fpl_mcp/.venv/bin/python -m fpl_mcp.server.

Deploying

The hosted server only reads the database. Data, training and predictions run on your own machine (or any scheduled job) with fpl-sync weekly, and the hosted server picks up new predictions within 10 minutes. You therefore need a database both can reach, such as Supabase.

1. Create a read-only database user for the public server: run scripts/supabase_readonly_role.sql in Supabase's SQL editor.
2. **Deploy