⚽ 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 modern Bearer token authentication (FPL_API_TOKEN / x-api-authorization) for private squad and live pick access.

• 🔌 Standard stdio Transport: Plug-and-play with any MCP-compliant client.

Related MCP server: MCP Eleven

🏗️ Architecture

fpl-mcp/
├── src/fpl_mcp/
│   ├── server.py          # MCP Server entrypoint (stdio transport)
│   ├── client.py          # Async FPL HTTP client with TTL caching
│   ├── auth.py            # Bearer token & session 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

# Preferred auth: Bearer JWT copied from browser
FPL_API_TOKEN=eyJhbGciOi...

# Legacy fallbacks / optional persistence (cookie or session file)
# FPL_COOKIE=
# FPL_SESSION_FILE=fpl_session.json

🔑 How to Get Your FPL_API_TOKEN

FPL uses Bearer token authentication via the x-api-authorization header rather than legacy pl_profile login cookies. To authenticate for private squad and live unconfirmed team data:

1. Log in to fantasy.premierleague.com.

2. Open your browser DevTools (F12 or Right-Click -> Inspect) and switch to the Network tab.

3. Refresh the page or click Pick Team / Transfers / Points.

4. Filter network requests by api/ or Fetch/XHR and click any request (e.g., my-team/...).

5. Under Request Headers, find x-api-authorization.

6. Copy the token string (strip the leading Bearer prefix).

7. Paste it into your .env file as FPL_API_TOKEN=....

⚙️ 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",
        "FPL_TEAM_ID": "1234567",
        "FPL_API_TOKEN": "your_token_here"
      }
    }
  }
}

🟣 Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "fpl": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/fpl-mcp",
        "run",
        "fpl-mcp"
      ],
      "env": {
        "FPL_TEAM_ID": "1234567",
        "FPL_API_TOKEN": "your_token_here"
      }
    }
  }
}

💻 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

2. Fixtures & Difficulty (FDR)

3. Squad & Manager Overview

4. Player Analytics

5. Transfers & Budget

6. Chips Strategy

7. Live Gameweek Scores

8. Mini-Leagues & Standings

9. Team News & Set Pieces

10. Captaincy & Differentials

11. Price Movements

💡 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:

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