The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the FPL Context listing page.
An MCP server that gives any MCP-capable AI agent a queryable Fantasy Premier League (FPL) database: player and match stats, fixtures, gameweeks, and every player's injury/availability status. It runs locally in Claude Desktop, Claude Code, Cursor, VS Code Copilot, Windsurf, Gemini CLI and Codex; ChatGPT and other clients that only accept a URL can connect when you host it over HTTP.
| Tool | What it does |
|---|---|
query_historical_stats | Runs a read-only SQL SELECT against a PostgreSQL database of FPL player, fixture and gameweek stats (whatever seasons you've ingested), including each player's FPL status, chance of playing, and injury/news note |
An ingestion job keeps that data populated and current:
| Job | What it does |
|---|---|
ingest_match_data | Fetches teams, fixtures, players (with availability) and per-match player stats from the FPL API, and writes them to PostgreSQL |
What it doesn't do: press coverage. Match reports, manager quotes and press-conference news aren't included — publishers' terms don't allow their articles to be stored and served through an AI tool. The tool description tells the model to use its own web search for that, which Claude, ChatGPT and Gemini all have. The division of labour: this server answers "who's injured, who's in form, what are the fixtures"; the AI's web search answers "what did the manager say".
This server does not fetch live data per-question. The tool only reads whatever is already sitting in your PostgreSQL database. It starts out empty — you must run the ingestion job once to seed it, and then keep running it on a recurring schedule forever, or answers will silently go stale. This is not a one-time setup step. See Keeping data fresh (ongoing) — it's the single most important thing to get right before handing this to anyone.
The full path from zero to a working MCP tool, in order. Each step links to details further down.
pip install fpl-context-mcp — see Installation.db/schema.sql against a fresh Postgres database — see Provisioning your database..env.example to .env and fill in your DATABASE_URL and DATABASE_ETL_URL — see Configuration.fpl-context-mcp --check — confirms every credential works before you go further.| Requirement | Version |
|---|---|
| Python | 3.11+ |
| PostgreSQL | Any recent version, with a read-only role (e.g. fpl_readonly) and a read/write role (e.g. fpl_etl) |
You provision the database yourself — see the next sections. Free tiers (Neon, Supabase, etc.) are plenty: the data is a few MB per season.
This installs three CLI commands: fpl-context-mcp (the MCP server), fpl-context-ingest-match (the recurring ingestion job), and fpl-context-backfill-history (a one-time job for past seasons) — see Seeding data.
The server reads all secrets from environment variables. Copy .env.example to .env in your working directory (it's gitignored) and fill in your own values:
| Component | Variables required |
|---|---|
query_historical_stats tool | DATABASE_URL |
ingest_match_data job | DATABASE_ETL_URL (or DATABASE_URL) |
Run fpl-context-mcp --check any time to confirm all of the above are set correctly and reachable — see Verifying connectivity.
db/schema.sql creates the six tables query_historical_stats expects (seasons, teams, gameweeks, players, fixtures, gw_player_stats) and includes example CREATE ROLE statements for the read-only and read/write roles referenced in .env.example. It's a starting schema, not a full migration tool — adjust types/constraints as needed.
The tables start completely empty. Continue to Seeding data.
The ingestion jobs are plain commands you run directly — nothing runs automatically on pip install or on MCP server startup.
Run these once, right after configuring your .env, before registering the server with Claude Desktop. Run fpl-context-ingest-match before the backfill. Until you do, query_historical_stats returns Query returned no results. for any query, since the tables are empty.
ingest_match_data loads the current season: every team, gameweek, player and fixture, plus per-player stats for matches already played (the first run can take several minutes mid-season, since it fetches stats player by player). Later runs are quick — see What each run updates.
fpl-context-backfill-history adds past seasons (as far back as FPL has them, about 20). It reads FPL's per-player season history and writes one row per player per season into players. It's safe to re-run and only needs to run once, since past seasons don't change. Know its limits:
team_fpl_id set to NULL (FPL doesn't say which team a player was on), and fpl_id is the player's current FPL id.This is not a one-time step. Fixtures change weekly, player stats update after every match, and injury/availability news changes daily. If you seed once and never run the job again, a query a month later will hit a database that's missing every result, stat and injury update since your last run.
You need something to invoke fpl-context-ingest-match on a recurring schedule, indefinitely, for as long as the MCP server is in use. (The backfill is not part of this — run it once.) Pick whichever fits your setup:
Runs are on a clock, not tied to gameweeks — nothing triggers when a match ends. A result shows up in your database at the first run after FPL marks the fixture finished.
| Job | Each run | Freshness with the default schedule |
|---|---|---|
fpl-context-ingest-match | Rewrites all teams, gameweeks (deadlines, current/next flags), players (points, form, price, and availability: status, chance of playing, news and when it changed) and all 380 fixtures (scores, finished flags, reschedules). Fetches per-player match stats for newly finished fixtures, and re-fetches those from the last 2 days because FPL revises bonus points after full time. | Up to about 12 hours behind (runs at 06:00 and 22:00 UTC) |
Run more often on matchdays if you want results sooner — each run takes a minute or two, and steady-state runs make very few requests to FPL.
Adjust the match-data cadence to the calendar:
| Period | Recommended cadence |
|---|---|
| PL season (Aug–May) | Twice daily, 0 6,22 * * * |
| World Cup / tournament group stage | Hourly, 0 * * * * |
| World Cup / tournament knockout | Every 6 hours, 0 */6 * * * |
| Off-season | Once daily, 0 8 * * * |
Best if you don't have a machine that's always on. You don't fork this project — you create a tiny repo of your own with one file that installs the package from PyPI and runs the ingestion command on a schedule.
Create a new private GitHub repository (any name).
Add this file as .github/workflows/ingest.yml:
In that repo: Settings → Secrets and variables → Actions → New repository secret, and add DATABASE_URL and DATABASE_ETL_URL.
Open the Actions tab, pick "Ingest sports data", and click Run workflow once to seed your data. From then on it runs by itself on the schedule.
Notes:
pip install fpl-context-mcp grabs the latest release on every run, so fixes arrive automatically. Pin a version (fpl-context-mcp==0.3.0) if you'd rather upgrade on purpose.Managed cron (Render, Railway, Fly.io machines, GCP Cloud Scheduler + Cloud Run Jobs, AWS EventBridge + Lambda/Fargate, systemd timers, Airflow, Dagster, etc.) all work the same way — point it at fpl-context-ingest-match (or python -m jobs.ingest_match_data) with the cadence table above and the environment variables from Configuration.
Whichever option you pick, re-run fpl-context-mcp --check afterward to confirm the scheduled job's credentials actually work in that environment — a job that silently fails every night is worse than no job, since nothing tells you the data's gone stale.
Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).
Tip: If you use
uv, replace"python"with"uv"and prepend"run"toargs:
Restart Claude Desktop. You should see fpl-context appear in the tools panel. If the tool returns nothing useful, re-check Seeding data and Keeping data fresh before assuming the server itself is broken.
Any client that can launch a local MCP server (stdio) works the same way: run the fpl-context-mcp command with DATABASE_URL in its environment. Swap in your own values below.
Claude Code
Cursor (~/.cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json) and Gemini CLI (~/.gemini/settings.json) all use the same mcpServers shape as Claude Desktop:
VS Code (Copilot agent mode) — .vscode/mcp.json in your workspace:
OpenAI Codex CLI — ~/.codex/config.toml:
Without installing first — if you have uv, use "command": "uvx" with "args": ["fpl-context-mcp"] in any of the configs above.
Your own agent code — the MCP SDKs (Python, TypeScript) and agent frameworks such as the OpenAI Agents SDK can launch fpl-context-mcp as a stdio server, or connect to it over HTTP as below.
Some clients can't launch a local process — they only accept a server URL. That includes ChatGPT (Settings → Apps & Connectors → Advanced → Developer mode → create a connector) and custom connectors on claude.ai. For these, run the server with the streamable HTTP transport on a machine with a public HTTPS address:
https://<your-host>/mcp; GET /health returns ok for load-balancer and platform health checks.--transport, --host and --port can also be set with MCP_TRANSPORT, MCP_HOST and MCP_PORT (or the PORT variable that Render, Cloud Run, Heroku and Fly set).cloudflared tunnel / ngrok for a quick test from your own machine.127.0.0.1, so nothing is exposed until you pass --host 0.0.0.0.Authentication. With MCP_AUTH_TOKEN set, every request to /mcp must send Authorization: Bearer <token>; others get HTTP 401. Clients that let you set headers can use it — for example Claude Code:
and the OpenAI Agents SDK / Responses API MCP tool (headers={"Authorization": "Bearer ..."}).
ChatGPT and claude.ai connectors only support OAuth or no authentication — not a static bearer token. To use them you currently have to leave
MCP_AUTH_TOKENunset (the endpoint is then open to anyone who finds the URL) or put an OAuth-capable proxy in front. If you run it open, understand what that exposes: anyone can run read-onlySELECTs against the database behindDATABASE_URL(10-second timeout, 100-row cap). Only do that with the dedicatedfpl_readonlyrole on a database that holds nothing but FPL data. The server logs a warning at startup when it's bound to a non-local address without a token.
Where the data comes from. A hosted server reads your database, exactly like a local one — you still need the ingestion job on a schedule (Keeping data fresh). And because you're now serving results to other people, see Data sources and disclaimer.
By default the server communicates over stdio — it is designed to be launched by an MCP client, and running it directly is mainly useful for smoke-testing startup and environment variable loading. To run it as a persistent network service instead, use --transport http (see Remote access over HTTP).
Before registering the server with a client — and any time something seems off — verify that your environment variables are correct and all backends are reachable:
Output example:
The command exits with code 0 if all required components pass, or 1 if any required component fails. Note that --check only verifies connectivity — it doesn't tell you whether your tables actually have data in them; for that, see Seeding data.
Set DRY_RUN=true to fetch data and verify routing without writing anything to PostgreSQL:
In dry-run mode:
DRY RUN MODE warning at startup so it is obvious from the logs.Accepted values for DRY_RUN: true, 1, yes (case-insensitive). Any other value (or absent) disables dry-run.
query_historical_statsExecutes a read-only SQL SELECT against the historical stats database.
Parameters
| Parameter | Type | Description |
|---|---|---|
sql | string | A SELECT statement. Mutations are rejected before reaching the database. LIMIT is injected automatically if omitted (capped at 100 rows). |
Example prompts
Safety
The tool enforces two layers of protection: a keyword blocklist rejects INSERT, UPDATE, DELETE, DROP, and similar statements before any database call is made, and the database connection uses a read-only role with no write grants.
The query_historical_stats tool has access to these tables (see db/schema.sql for the full DDL if provisioning standalone):
Current vs past seasons: teams, gameweeks, fixtures and gw_player_stats hold the current season only. players also holds one totals-only row per player per past season (see Seeding data for what that covers and what it misses).
Availability: status is a available, d doubtful, i injured, s suspended, u unavailable, n not in squad. chance_of_playing_next_round is 0–100 (NULL means no concern), news is FPL's one-line note, and news_added is when that note last changed. Databases created before 0.7.0 get the news_added column added automatically on the next ingestion run (if the ETL role owns the table; otherwise the job logs the one-line ALTER TABLE to run).
Join hint: teams.fpl_id = players.team_fpl_id (current season, same season_id; team_fpl_id is NULL for past seasons).
The test suite covers:
| File | What's tested |
|---|---|
tests/test_config.py | Env var reading, defaults, dotenv loading, dry-run flag |
tests/test_tools_stats.py | Mutation guard, row formatter, async DB path, dry-run |
tests/test_ingest_match_data.py | Fixture/gameweek/player upserts, news_added migration, stats selection, thread coordination, rollback, dry-run |
tests/test_server_http.py | HTTP transport: bearer-token auth, /health, no /mcp redirect, CLI/env argument parsing |
tests/test_backfill_history.py | Past-season backfill: season handling, NULL team, best-effort ALTER, exit codes |
fpl-context-mcp is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by the Premier League or Fantasy Premier League.
The package ships no data. The ingestion jobs fetch it, on your machine and under your credentials, from:
| Source | Used for | Notes |
|---|---|---|
Fantasy Premier League API (fantasy.premierleague.com/api) | Players, teams, fixtures, match stats, injury/availability news | Unofficial and undocumented; it can change or rate-limit without notice. |
No news articles. Earlier versions (before 0.7.0) also ingested BBC Sport and Guardian articles into a Pinecone index. That was removed: the Guardian's Open Platform terms prohibit using its content with AI technologies and storing it for more than 24 hours, and BBC feeds are licensed for personal, non-commercial use. For press coverage, let your AI client use its own web search.
You are responsible for complying with each source's terms of use for the data you ingest, store, and — if you host the server for other people — serve. This is especially relevant for commercial use and for public deployments. The MIT license below covers this project's code only, not any third-party content it retrieves.
MIT © 2026 Shubham Banthia