fpl-context-mcp

# fpl-context-mcp

<!-- mcp-name: io.github.sbanthia92/fpl-context-mcp -->

An [MCP](https://modelcontextprotocol.io) 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](#remote-access-over-http-chatgpt-and-other-url-only-clients).

| 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)](#keeping-data-fresh-ongoing) — it's the single most important thing to get right before handing this to anyone.

---

## Contents

- [Quickstart](#quickstart)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Provisioning your database](#provisioning-your-database)
- [Seeding data (required before first use)](#seeding-data-required-before-first-use)
- [Keeping data fresh (ongoing)](#keeping-data-fresh-ongoing)
- [Registering with Claude Desktop](#registering-with-claude-desktop)
- [Other AI clients (local)](#other-ai-clients-local)
- [Remote access over HTTP (ChatGPT and other URL-only clients)](#remote-access-over-http-chatgpt-and-other-url-only-clients)
- [Running the server standalone](#running-the-server-standalone)
- [Verifying connectivity (--check)](#verifying-connectivity---check)
- [Dry-run mode](#dry-run-mode)
- [MCP tools reference](#mcp-tools-reference)
- [Database schema](#database-schema)
- [Running tests](#running-tests)
- [Data sources and disclaimer](#data-sources-and-disclaimer)
- [License](#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](#installation).
2. **Provision storage**: a PostgreSQL database. Run [`db/schema.sql`](db/schema.sql) against a fresh Postgres database — see [Provisioning your database](#provisioning-your-database).
3. **Configure**: copy [`.env.example`](.env.example) to `.env` and fill in your `DATABASE_URL` and `DATABASE_ETL_URL` — see [Configuration](#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](#seeding-data-required-before-first-use).
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](#keeping-data-fresh-ongoing). Skipping this is the #1 cause of "the tool returns nothing" reports.
7. **Connect your AI client**: [Claude Desktop](#registering-with-claude-desktop), [Claude Code, Cursor, VS Code, Windsurf, Gemini CLI or Codex](#other-ai-clients-local), or — for ChatGPT and other clients that only accept a URL — [run it over HTTP](#remote-access-over-http-chatgpt-and-other-url-only-clients).

---

## Prerequisites

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

---

## Installation

### From PyPI (recommended)

```bash
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](#seeding-data-required-before-first-use).

### With uv

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

### With pip (from source)

```bash
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`](.env.example) to `.env` in your working directory (it's gitignored) and fill in your own values:

```dotenv
# 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?

| 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](#verifying-connectivity---check).

---

## Provisioning your database

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

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

---

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

```bash
# 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](#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.

| Job | Each run | Freshness with the default schedule |
|---|