fpl-context-mcp

An MCP server that gives any MCP-capable AI agent two tools for answering Fantasy Premier League (FPL) and Premier League football questions. 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.

Two ingestion jobs keep that data populated and current:

This server does not fetch live data per-question. The two tools above only read whatever is already sitting in your PostgreSQL database and Pinecone index. Those stores start out empty — you must run the ingestion jobs once to seed them, and then keep running them on a recurring schedule forever, or answers will silently go stale (press results) or stay empty (stats results). 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

• Extending with new press sources

• Data sources and disclaimer

• License

Related MCP server: FPL MCP Server

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 and a Pinecone index. Run db/schema.sql against a fresh Postgres database and create a Pinecone index named fpl-context (or your own name) using the multilingual-e5-large model — see Provisioning your own database.

3. Configure: copy .env.example to .env and fill in your DATABASE_URL, DATABASE_ETL_URL, and PINECONE_API_KEY — see Configuration.

4. Verify connectivity: fpl-context-mcp --check — confirms every credential works before you go further.

5. Seed data: run the two ingestion commands, 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 two ingestion commands (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 both yourself — see the next two sections. Both have free tiers that are enough for this.

Installation

From PyPI (recommended)

pip install fpl-context-mcp

This installs four CLI commands: fpl-context-mcp (the MCP server), fpl-context-ingest-press and fpl-context-ingest-match (the two recurring ingestion jobs), 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

# Pinecone — required for both the press tool and the ingest_press_content job
PINECONE_API_KEY=pcsk_...
PINECONE_INDEX_NAME=fpl-context   # optional, defaults to 'fpl-context'

# The Guardian open platform API key
# Register free at https://open-platform.theguardian.com/access/
# Recommended: without a key the Guardian source is skipped (BBC Sport only) —
# the old public 'test' key is rejected by the API.
GUARDIAN_API_KEY=your-key-here

# 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

PostgreSQL:

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.

Pinecone:

1. Create a free account at pinecone.io if you don't have one.

2. Create an index named fpl-context (or any name — just set PINECONE_INDEX_NAME to match) configured for the multilingual-e5-large integrated embedding model (1024 dimensions, cosine metric). No separate embedding step needed — the ingestion job and the query tool both call Pinecone's built-in inference.

3. Grab an API key from the Pinecone console and set PINECONE_API_KEY.

Both tables and the index start completely empty. Continue to Seeding data.

Seeding data (required before first use)

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

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

# If running from source
python -m jobs.ingest_press_content
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_press_conferences will return a message telling you the namespace is unseeded, instead of any article content.

• query_historical_stats will return 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.

ingest_press_content only pulls currently-live articles (BBC/Guardian don't offer deep history), so the press index will be thin until it's had a few days of scheduled runs — that's expected, not a bug.

Keeping data fresh (ongoing)

This is not a one-time step. Fixtures change weekly, player stats update after every match, press articles are deleted from the index after 14 days, and injury/availability news is rewritten on every run so it reflects what FPL currently says (ingest_press_content prunes stale docs each time). If you seed once and never run these jobs again, a query a month later will hit a Pinecone namespace with zero documents (everything aged out) and a Postgres database that's missing every fixture since your last run.

You need something to invoke fpl-context-ingest-press and 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.

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.

Option A — cron (simplest, any Linux/macOS host)

# Press content: nightly at midnight UTC
0 0 * * * /path/to/venv/bin/fpl-context-ingest-press >> /var/log/fpl-context-ingest-press.log 2>&1

# Match data: twice daily during the season (06:00 + 22:00 UTC)
0 6,22 * * * /path/to/venv/bin/fpl-context-ingest-match >> /var/log/fpl-context-ingest-match.log 2>&1

Adjust the match-data cadence to the calendar:

Option B — GitHub Actions in your own private repo (free, no server needed)

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 two commands on a schedule.

1. Create a new private GitHub repository (any name).

2. Add this file as .github/workflows/ingest.yml:

   name: Ingest sports data
   
   on:
     schedule:
       - cron: "0 6,22 * * *" # twice daily, UTC
     workflow_dispatch: {} # lets you run it by hand from the Actions tab
   
   jobs:
     ingest:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/setup-python@v5
           with:
             python-version: "3.11"
         - run: pip install fpl-context-mcp
         - name: Ingest press content
           run: fpl-context-ingest-press
           env:
             PINECONE_API_KEY: ${{ secrets.PINECONE_API_KEY }}
             PINECONE_INDEX_NAME: ${{ secrets.PINECONE_INDEX_NAME }}
             GUARDIAN_API_KEY: ${{ secrets.GUARDIAN_API_KEY }}
         - name: Ingest match data
           run: fpl-context-ingest-match
           env:
             DATABASE_URL: ${{ secrets.DATABASE_URL }}
             DATABASE_ETL_URL: ${{ secrets.DATABASE_ETL_URL }}

3. In that repo: Settings → Secrets and variables → Actions → New repository secret, and add PINECONE_API_KEY, DATABASE_URL, and DATABASE_ETL_URL. GUARDIAN_API_KEY is strongly recommended — without it the Guardian source is skipped and only BBC Sport articles are ingested (register a free key at open-platform.theguardian.com). PINECONE_INDEX_NAME is optional and defaults to fpl-context.

4. 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:

• A failed run turns red and GitHub emails you (missing credentials, a database that's unreachable, an API outage), so you'll know if data stops flowing.

• Updates: 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.

• Cost: each run takes about a minute or two, so a twice-daily schedule stays well inside GitHub's free monthly minutes for private repos.

• Why private: GitHub automatically pauses scheduled workflows in public repos after 60 days without a commit. Private repos aren't paused.

Option C — any other scheduler

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-press and fpl-context-ingest-match (or the python -m jobs.* equivalents) 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.

Registering with Claude Desktop

Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

If installed from PyPI (recommended)

{
  "mcpServers": {
    "fpl-context": {
      "command": "fpl-context-mcp",
      "env": {
        "DATABASE_URL": "postgresql://fpl_readonly:password@localhost:5432/fpl",
        "PINECONE_API_KEY": "pcsk_..."
      }
    }
  }
}

If running from source

{
  "mcpServers": {
    "fpl-context": {
      "command": "python",
      "args": ["/absolute/path/to/fpl-context-mcp/server.py"],
      "env": {
        "DATABASE_URL": "postgresql://fpl_readonly:password@localhost:5432/fpl",
        "PINECONE_API_KEY": "pcsk_..."
      }
    }
  }
}

Tip: If you use uv, replace "python" with "uv" and prepend "run" to args:

"command": "uv",
"args": ["run", "/absolute/path/to/fpl-context-mcp/server.py"]

Restart Claude Desktop. You should see fpl-context appear in the tools panel. If either tool returns nothing useful, re-check Seeding data and Keeping data fresh before assuming the server itself is broken.

Other AI clients (local)

Any client that can launch a local MCP server (stdio) works the same way: run the fpl-context-mcp command with DATABASE_URL and PINECONE_API_KEY in its environment. Swap in your own values below.

Claude Code

claude mcp add fpl-context -e DATABASE_URL=postgresql://fpl_readonly:password@localhost:5432/fpl -e PINECONE_API_KEY=pcsk_... -- fpl-context-mcp

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:

{
  "mcpServers": {
    "fpl-context": {
      "command": "fpl-context-mcp",
      "env": {
        "DATABASE_URL": "postgresql://fpl_readonly:password@localhost:5432/fpl",
        "PINECONE_API_KEY": "pcsk_..."
      }
    }
  }
}

VS Code (Copilot agent mode) — .vscode/mcp.json in your workspace:

{
  "servers": {
    "fpl-context": {
      "type": "stdio",
      "command": "fpl-context-mcp",
      "env": {
        "DATABASE_URL": "postgresql://fpl_readonly:password@localhost:5432/fpl",
        "PINECONE_API_KEY": "pcsk_..."
      }
    }
  }
}

OpenAI Codex CLI — ~/.codex/config.toml:

[mcp_servers.fpl-context]
command = "fpl-context-mcp"
env = { DATABASE_URL = "postgresql://fpl_readonly:password@localhost:5432/fpl", PINECONE_API_KEY = "pcsk_..." }

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.

Remote access over HTTP (ChatGPT and other URL-only clients)

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:

MCP_AUTH_TOKEN=some-long-random-string \
fpl-context-mcp --transport http --host 0.0.0.0 --port 8000

• The MCP endpoint is 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).

• The server listens on plain HTTP. Put it behind something that terminates TLS — any of those platforms does, or cloudflared tunnel / ngrok for a quick test from your own machine.

• The default bind address is 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:

claude mcp add --transport http fpl-context https://your-host/mcp --header "Authorization: Bearer some-long-random-string"

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_TOKEN unset (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-only SELECTs against the database behind DATABASE_URL (10-second timeout, 100-row cap) and use up your Pinecone query quota. Only do that with the dedicated fpl_readonly role 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 and index, exactly like a local one — you still need the ingestion jobs on a schedule (Keeping data fresh). And because you're now serving results to other people, see Data sources and disclaimer.

Running the server standalone

# If installed from PyPI
fpl-context-mcp

# If running from source
python server.py

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

Verifying connectivity (--check)

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:

# If installed from PyPI
fpl-context-mcp --check

# If running from source
python server.py --check

Output example:

=== fpl-context-mcp configuration check ===

✅ Pinecone          connected (index: 'fpl-context')
✅ PostgreSQL (RO)   connected (localhost:5432/fpl)
✅ PostgreSQL (ETL)  connected (localhost:5432/fpl)
✅ Guardian API      registered key configured

✅ All required components OK

The command exits with code 0 if all required components pass, or 1 if any required component fails. Optional components (Guardian API) emit warnings but do not cause a non-zero exit — a missing GUARDIAN_API_KEY just means Guardian articles are skipped. Note that --check only verifies connectivity — it doesn't tell you whether your tables/index actually have data in them; for that, see Seeding data.

Dry-run mode

Set DRY_RUN=true to fetch data and verify routing without writing anything to Pinecone or PostgreSQL:

DRY_RUN=true fpl-context-mcp
DRY_RUN=true fpl-context-ingest-press

In dry-run mode:

• Tools return a human-readable description of the call that would have been made — the SQL with host, or the Pinecone index/namespace/params — without opening any connection.

• Ingestion jobs still call all external APIs (verifying connectivity) but skip every Pinecone and PostgreSQL write. Log output shows how many documents would have been upserted.

• The server logs a 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.

MCP tools reference

query_historical_stats

Executes a read-only SQL SELECT against the historical stats database.

Parameters

Example prompts

• "Who are the top 10 midfielders by total points this season?"

• "Which players have scored the most goals this season?"

• "Show my captain candidate's goals and points over the last five seasons." (past seasons only cover players still in the current FPL list)

• "When is the next gameweek deadline?"

• "Which teams have the best defensive record at home this season?"

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.

query_press_conferences

Semantic search over Premier League press coverage ingested from BBC Sport and The Guardian.

Parameters

Ranking formula

Results are re-ranked after retrieval:

final_score = semantic_score × (1 + recency_weight × recency_score)

recency_score is 1.0 for an article published today and decays toward 0.1 over 14 days.

Example prompts

• "Any injury concerns for Saka this week?"

• "What did Slot say about Salah's contract situation?"

• "Who is doubtful for Arsenal's next match?"

No results? If the press namespace hasn't been seeded yet, or everything in it has aged out past 14 days, this tool returns a message explaining that instead of an empty response — see Keeping data fresh.

Database schema

The query_historical_stats tool has access to these tables (see db/schema.sql for the full DDL if provisioning standalone):

seasons          id, label (e.g. '2025/26'), start_year, is_current

teams            season_id, fpl_id, name, short_name, strength,
                 strength_attack_home/away, strength_defence_home/away

gameweeks        season_id, gw_number (1–38), deadline_time, is_current,
                 is_next, is_finished, average_entry_score, highest_score

players          season_id, fpl_id, team_fpl_id, first_name, second_name,
                 web_name, position (GKP/DEF/MID/FWD), now_cost, form,
                 total_points, minutes, goals_scored, assists, clean_sheets,
                 expected_goals, expected_assists, ict_index, status, news

fixtures         season_id, fpl_id, gw_number, kickoff_time,
                 home_team_fpl_id, away_team_fpl_id, home_score, away_score,
                 finished, home_team_difficulty, away_team_difficulty

gw_player_stats  season_id, player_fpl_id, gw_number, fixture_fpl_id,
                 opponent_team_fpl_id, was_home, minutes, goals_scored,
                 assists, clean_sheets, bonus, total_points,
                 expected_goals, expected_assists, ict_index, starts

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

Join hint: teams.fpl_id = players.team_fpl_id (current season, same season_id; team_fpl_id is NULL for past seasons).

Running tests

# Install dev dependencies if you haven't already
pip install -e ".[dev]"

# Run the full suite (all mocked — no real DB or API calls)
pytest tests/ -v

# Lint and format
ruff check . && ruff format .

The test suite covers:

Extending with new press sources

To add a new press source, subclass _BaseFetcher in jobs/ingest_press_content.py and add an instance to the FETCHERS list. The orchestrator picks it up automatically — no other changes needed.

class MySportsFetcher(_BaseFetcher):
    source_name = "My Sports Site"

    def fetch(self) -> list[tuple[str, str, dict]]:
        # return a list of (doc_id, text, metadata) tuples
        ...


FETCHERS: list[_BaseFetcher] = [BBCSportFetcher(), GuardianAPIFetcher(), MySportsFetcher()]

Each tuple is (doc_id, text, metadata) where:

• doc_id — a stable 32-char hex ID (use _doc_id(source + url))

• text — the full text to embed, prefixed with the source name

• metadata — must include type, source, recency_score, and pub_timestamp

Data sources and disclaimer

fpl-context-mcp is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by the Premier League, Fantasy Premier League, the BBC, or Guardian News & Media.

The package ships no data. The ingestion jobs fetch it, on your machine and under your credentials, from:

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.

License

MIT © 2026 Shubham Banthia