⚽ FPL MCP — Model Context Protocol Server for Fantasy Premier League

An asynchronous Model Context Protocol (MCP) server for Fantasy Premier League (FPL). Equips AI coding assistants and agent frameworks (Antigravity, Claude Desktop, Cursor, Custom Agents) with 33 dedicated tools to analyze fixtures, scout differentials, manage squads, track live scores, monitor price fluctuations, and optimize transfers and captaincy decisions.

---

🌟 Key Features

• 🚀 33 Specialized Tools: Complete coverage of official FPL endpoints (Bootstrap, Fixtures, FDR, Squad, History, Chips, Live Gameweek Scores, Mini-Leagues, Set-Piece Takers, Differentials, and Price Movers).
• 🔒 Safe & Read-Only: Focuses on deep analytics and AI recommendations without risky automated transfers.
• ⚡ In-Memory TTL Caching: Intelligent per-endpoint caching prevents rate limiting from FPL servers while keeping live gameweek scores fresh.
• 🛡️ Public & Private Support: Works immediately for public data with just a team ID. Supports session auth / cookies for private squad access.
• 🔌 Standard stdio Transport: Plug-and-play with any MCP-compliant client.

---

🏗️ Architecture

fpl-mcp/
├── src/fpl_mcp/
│   ├── server.py          # MCP Server entrypoint (stdio transport)
│   ├── client.py          # Async FPL HTTP client with TTL caching
│   ├── auth.py            # Session cookie & credential manager
│   ├── cache.py           # In-memory thread-safe TTL cache
│   ├── constants.py       # API endpoints, TTLs, positions & chip maps
│   └── tools/
│       ├── registry.py    # Aggregator & dynamic tool dispatcher
│       ├── bootstrap.py   # Players, teams, and season status
│       ├── fixtures.py    # Fixtures schedule & FDR matrix
│       ├── squad.py       # Team picks, history, and manager info
│       ├── players.py     # Deep player statistics (xG, xA, ICT, PPG)
│       ├── transfers.py   # Transfer history, bank, and AI transfer scout
│       ├── chips.py       # Chip tracker & Double/Blank GW strategy engine
│       ├── live.py        # Real-time provisional GW scores & bonus points
│       ├── leagues.py     # Classic & Head-to-Head mini-league tables
│       ├── news.py        # Injury reports, bans, and set-piece takers
│       ├── picks.py       # Algorithmically ranked captain picks & differentials
│       └── prices.py      # Predicted price risers/fallers & confirmed changes
├── pyproject.toml
└── README.md

---

🚀 Quick Start

1. Prerequisites

• Python 3.11+
• uv (recommended) or pip

2. Installation

# Clone the repository
git clone https://github.com/dexhamter/fpl-mcp.git
cd fpl-mcp

# Install dependencies into virtual environment
uv sync

3. Configuration

Copy the example environment file:

cp .env.example .env

Edit .env with your team information:

# Your FPL Team ID (found in the URL: https://fantasy.premierleague.com/entry/{ID}/event/1)
FPL_TEAM_ID=1234567

# Optional: FPL login credentials or browser session cookie for private team data
FPL_EMAIL=your@email.com
FPL_PASSWORD=your_password
# FPL_COOKIE=pl_profile=...

---

⚙️ Connecting to MCP Clients

🤖 Antigravity / Gemini CLI

Add the server to your ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "fpl": {
      "command": "C:/Users/your_user/Documents/fpl/.venv/Scripts/python.exe",
      "args": ["-m", "fpl_mcp.server"],
      "env": {
        "PYTHONPATH": "C:/Users/your_user/Documents/fpl/src"
      }
    }
  }
}

🟣 Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "fpl": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/fpl-mcp",
        "run",
        "fpl-mcp"
      ]
    }
  }
}

💻 Cursor / Windsurf

In Settings -> Features -> MCP Servers:

• Type: command
• Command: uv --directory /path/to/fpl-mcp run fpl-mcp

---

🛠️ Tool Catalog (33 Tools)

1. General & Bootstrap Data

Tool	Arguments	Description
get_all_players	position, team, max_price, min_form	Query all active players with filtering & sorting
search_player	query (required)	Search for players by partial or full name
get_all_teams	None	Get all 20 Premier League teams with strength ratings
get_game_settings	None	Gameweek deadline, average score, top managers

2. Fixtures & Difficulty (FDR)

Tool	Arguments	Description
get_fixtures	gameweek	All or specific gameweek match schedules
get_team_fixtures	team_name (required), next_n	Upcoming schedule for a team with FDR ratings
get_fdr_table	next_n	Comparative FDR grid across all teams

3. Squad & Manager Overview

Tool	Arguments	Description
get_my_squad	None	Current 15-player squad, starters, bench, captaincy
get_entry_info	team_id	Overall rank, total points, bank balance, and team value
get_gw_picks	gameweek (required), team_id	Squad lineup for any completed gameweek
get_season_history	team_id	Gameweek-by-gameweek rank and point trajectory

4. Player Analytics

Tool	Arguments	Description
get_player_stats	player_id, player_name	xG, xA, ICT index, bonus points, minutes, form
get_player_history	player_id, player_name	Detailed per-gameweek match log for a player
get_top_performers	sort_by, position, max_price, limit	Ranked leaderboard by points, form, PPG, or ICT

5. Transfers & Budget

Tool	Arguments	Description
get_transfer_history	team_id	Full season transfer log with buy/sell costs
get_bank_balance	None	Available in-the-bank funds, free transfers, team value
get_transfer_suggestions	position, max_price, next_n_gws	Composite algorithm scouting transfers by form & FDR

6. Chips Strategy

Tool	Arguments	Description
get_chip_status	None	Tracker for Wildcards, Free Hit, Bench Boost, Triple Captain
get_chip_advice	next_n	Double/Blank Gameweek detection and optimal chip timing

7. Live Gameweek Scores

Tool	Arguments	Description
get_live_gw_scores	gameweek, sort_by, limit	Real-time provisional player points, goals, assists
get_my_live_score	gameweek	Real-time running total for your squad with active captain multiplier

8. Mini-Leagues & Standings

Tool	Arguments	Description
get_my_leagues	None	All classic and head-to-head mini-leagues for your team
get_classic_league_standings	league_id (required), page	Full leaderboard table with ranks and event scores
get_h2h_league_standings	league_id (required), page	Head-to-head records (W/D/L, match points)

9. Team News & Set Pieces

Tool	Arguments	Description
get_player_news	status	Filter players with injuries, suspensions, or doubts
get_set_piece_takers	team_name	Designated penalty, free-kick, and corner takers
check_my_squad_news	None	Health check across your 15 players with status alerts

10. Captaincy & Differentials

Tool	Arguments	Description
get_captain_suggestions	from_my_squad, gameweek, top_n	Multi-factor weighted captain score (Form, ICT, FDR, Home)
get_differentials	max_ownership, position, max_price	High-potential low-ownership picks (<15% default)
get_ownership_stats	position, sort_by, limit	Ownership %, transfer momentum, and net delta

11. Price Movements

Tool	Arguments	Description
get_price_risers	position, limit	Imminent price risers based on net incoming transfers
get_price_fallers	position, limit	Imminent price fallers based on net outgoing transfers
get_price_changes	direction, since	Confirmed price alterations this gameweek or season

---

💡 Example Assistant Prompts

Once configured with your agent, you can ask natural language questions like:

• "Who should I captain for Gameweek 1? Compare my best options based on fixtures and expected goal involvement."
• "Check my squad for any injury concerns before the deadline."
• "I have £0.5m in the bank and need to replace a midfielder under £7.5m with easy upcoming fixtures. Who do you suggest?"
• "Show me the top 5 differential forwards owned by less than 10% of managers."
• "Who is on penalty duties for Arsenal and Liverpool this season?"
• "What is our strategy for Double and Blank Gameweeks? When should I consider using my Bench Boost?"

---

⏱️ Caching Policy

To preserve low latency and comply with FPL server etiquette, data is cached in-memory:

Endpoint Type	Default TTL
Live Gameweek Scores (live.py)	60 seconds
Squad & Entry Info (squad.py)	120 - 300 seconds
Bootstrap & Player Stats (bootstrap.py, players.py)	300 seconds (5 min)
Fixtures & Schedule (fixtures.py)	600 seconds (10 min)

---

📜 License

This project is licensed under the MIT License.

---

⚽ Disclaimer

This tool is not officially affiliated with or endorsed by the Premier League or Fantasy Premier League. All data is fetched from public FPL API endpoints.