fantasy-pl-mcp is a Model Context Protocol (MCP) server that provides access to Fantasy Premier League (FPL) data and tools. It allows you to interact with FPL data in Claude for Desktop and other MCP-compatible clients.
Purpose
This project is aimed at Fantasy Premier League players and data analysts, with the goal of directly querying, analyzing, and comparing FPL data in desktop LLM clients that support MCP, to assist with decisions on lineups, transfers, captains, and more.
Main capabilities
- Rich player data: access comprehensive player statistics provided by the FPL API.
- Team information: get details on Premier League teams.
- Gameweek data: view current and past gameweek information.
- Player search: find players by name or team.
- Player comparison: compare detailed statistics for any two players.
- Fixtures and gameweeks: analyze upcoming fixtures and difficulty ratings for players, teams, or positions, get blank gameweek and double gameweek information, and view live gameweek scores and the official Fantasy lineup.
- Personal team and advice: captain ratings and recommendations, view authenticated teams, manager details, transfer history, classic league rankings, and league analysis.
- Prompt templates: prompt templates for player analysis, transfer recommendations, team ratings, differential players, chip strategy, and more.
How to use
Supported platforms include Claude for Desktop and other MCP-compatible desktop LLMs; mobile is currently not supported. Python 3.10 or higher is required, as well as Claude Desktop (for AI integration).
Installation methods:
- Install from PyPI (recommended)
- Install development dependencies
- Install from GitHub
- Clone and install locally
Running the server:
- Use the CLI command
- Use the Python module
- Use with Claude Desktop: edit the claude_desktop_config.json file to configure it. Method one: use the Python module directly (most reliable); method two: use the full path to the installed command (if installed via pip). Note that using only "command": "fpl-mcp" may occur because Claude Desktop cannot access the virtual environment PATH spawn fpl-mcp ENOENT error; using the full path or the Python module method avoids this.
In Claude for Desktop: after launching, you should see the FPL tools provided via the hammer icon. Example queries include: "Compare Mohamed Salah and Erling Haaland over the last 5 gameweeks", "Find all Arsenal midfielders", "What's the current gameweek status?", "Show me the top 5 forwards by points".
Authentication: FPL has migrated login to PingOne (Ping Identity) OIDC, so authentication uses an OIDC refresh token rather than email and password. The refresh token is automatically exchanged for a short-lived access token, and requests are sent with the X-API-Authorization: Bearer header. To use features that require authentication (such as accessing your personal team or private leagues), you need to set a refresh token. Running the fpl-mcp-config interactive tool guides you through copying the OIDC refresh token from the browser and prompts you to enter the refresh token and team ID, saving them encrypted to ~/.fpl-mcp/credentials.enc. To obtain a refresh token: log in in the browser https://fantasy.premierleague.com，打开 DevTools Console (F12 → Console) and run the specified code; or via DevTools → Application → Local storage, copy the complete JSON value of the key starting with oidc.user:. After setting, run fpl-mcp-config test to test authentication. It can also be configured manually: create a ~/.fpl-mcp/.env file, ~/.fpl-mcp/config.json, or set environment variables. Note that the refresh token may be rotated or revoked by FPL; if authentication fails, rerun fpl-mcp-config setup and use the newly copied token.
Available resources include: fpl://static/players, fpl://static/players/{name}, fpl://static/teams, fpl://static/teams/{name}, fpl://gameweeks/current, fpl://gameweeks/all, fpl://fixtures, fpl://fixtures/gameweek/{gameweek_id}, fpl://fixtures/team/{team_name}, fpl://players/{player_name}/fixtures, fpl://gameweeks/blank, fpl://gameweeks/double.
Available tools include: search_fpl_players, get_player_information, analyze_players, compare_players, get_price_changes, get_gameweek_status, analyze_player_fixtures, analyze_fixtures, get_blank_gameweeks, get_double_gameweeks, get_gameweek_live_scores, get_dream_team, suggest_captain, check_fpl_authentication, update_fpl_credentials, get_my_team, get_my_current_team, get_team, get_manager, get_manager_info, get_manager_transfer_history, get_league_standings, get_league_analytics.
Prompt templates include: player_analysis_prompt, transfer_advice_prompt, team_rating_prompt, differential_players_prompt, chip_strategy_prompt.
Applicable Scenarios
Suitable for operations such as FPL player comparison, team filtering, fixture difficulty analysis, captain selection, transfer advice, and league standings analysis in MCP-compatible clients such as Claude for Desktop.
Limitations
- Mobile is currently not supported.
- The FPL API has no official documentation and may change at any time.
- Currently only read operations are supported.
- Requires Python 3.10 or higher.
- Authentication depends on the OIDC refresh token, which may be rotated or revoked.
- The project uses the MIT license.
