fpl-context-mcp

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.

An ingestion job keeps that data populated and current:

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.

Contents

• Quickstart
• Prerequisites
• Installation
• Configuration
• Provisioning your database
• Seeding data (required before first use)
• Keeping data fresh (ongoing)
• Registering with Claude Desktop
• Other AI clients (local)
• Remote access over HTTP (ChatGPT and other URL-only clients)
• Running the server standalone
• Verifying connectivity (--check)
• Dry-run mode
• MCP tools reference
• Database schema
• Running tests
• Data sources and disclaimer
• License

Quickstart

The full path from zero to a working MCP tool, in order. Each step links to details further down.

1. Install: pip install fpl-context-mcp — see Installation.
2. Provision storage: a PostgreSQL database. Run db/schema.sql against a fresh Postgres database — see Provisioning your database.
3. Configure: copy .env.example to .env and fill in your DATABASE_URL and DATABASE_ETL_URL — see Configuration.
4. Verify connectivity: fpl-context-mcp --check — confirms every credential works before you go further.
5. Seed data: run the match ingestion command, then the one-time history backfill, so there's actually something to query — see Seeding data.
6. Schedule ongoing ingestion: set up cron (or equivalent) to keep re-running the match ingestion command (not the backfill) indefinitely — see Keeping data fresh. Skipping this is the #1 cause of "the tool returns nothing" reports.
7. Connect your AI client: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Gemini CLI or Codex, or — for ChatGPT and other clients that only accept a URL — run it over HTTP.

Prerequisites

You provision the database yourself — see the next sections. Free tiers (Neon, Supabase, etc.) are plenty: the data is a few MB per season.

Installation

From PyPI (recommended)

pip install fpl-context-mcp

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.

With uv

git clone https://github.com/sbanthia92/fpl-context-mcp
cd fpl-context-mcp
uv sync

With pip (from source)

git clone https://github.com/sbanthia92/fpl-context-mcp
cd fpl-context-mcp
pip install -e ".[dev]"

As a dependency of another project

fpl-context-mcp @ git+https://github.com/sbanthia92/fpl-context-mcp.git

Configuration

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:

# PostgreSQL — read-only connection for the query_historical_stats tool
DATABASE_URL=postgresql://fpl_readonly:password@localhost:5432/fpl

# PostgreSQL — read/write connection for the ingest_match_data job
# Falls back to DATABASE_URL if not set
DATABASE_ETL_URL=postgresql://fpl_etl:password@localhost:5432/fpl

# HTTP transport only (fpl-context-mcp --transport http). Requests to /mcp must
# send "Authorization: Bearer <token>". Leave empty only when bound to localhost.
# MCP_AUTH_TOKEN=

Which variables does each component need?

Run fpl-context-mcp --check any time to confirm all of the above are set correctly and reachable — see Verifying connectivity.

Provisioning your database

createdb fpl   # or whatever database name you'll use in DATABASE_URL
psql fpl -f db/schema.sql

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.

Seeding data (required before first use)

The ingestion jobs are plain commands you run directly — nothing runs automatically on pip install or on MCP server startup.

# If installed from PyPI
fpl-context-ingest-match
fpl-context-backfill-history   # one-time: past seasons (see below)

# If running from source
python -m jobs.ingest_match_data
python -m jobs.backfill_history

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:

• It holds season totals only — points, minutes, goals, assists, clean sheets, cards, bonus. FPL doesn't serve past fixtures, teams or match-by-match stats, so those tables only ever contain the current season.
• Past-season rows have 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.
• It only covers players in FPL's current player list. Anyone who has left the league (or retired) has no history here, so a question about a departed player returns nothing, and league-wide or team-wide totals for a past season are incomplete. Per-player questions about current players are reliable.

Keeping data fresh (ongoing)

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:

What each run updates

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.