Fantasy Premier League

What is Fantasy Premier League about?

Offers a Model Context Protocol server that surfaces rich FPL data—player stats, team details, current and historic gameweeks, fixtures, and a suite of analytical tools—so LLM clients like Claude for Desktop can query and reason over real‑time fantasy football information.

How to use Fantasy Premier League?

Install the package (recommended via PyPI): pip install fpl-mcp.
Start the server using one of the supported commands:
- CLI shortcut: fpl-mcp
- Python module: python -m fpl_mcp

Configure your LLM client (e.g., Claude Desktop) to point to the server, preferably using the Python module:

{
  "mcpServers": {
    "fantasy-pl": {
      "command": "python",
      "args": ["-m", "fpl_mcp"]
    }
  }
}

Authenticate (optional) for private actions such as viewing your own team: run fpl-mcp-config setup and follow the prompts.
Query the server using resource URLs (fpl://static/players, fpl://gameweeks/current, etc.) or invoke the provided tools (compare_players, analyze_fixtures, …).

Key features of Fantasy Premier League

Rich Player Data – Comprehensive statistics from the official FPL API.
Team & Fixture Information – Up‑to‑date squad details and upcoming match difficulties.
Gameweek Insights – Current, past, blank, and double gameweek data.
Search & Comparison – Find players by name/team and compare any two players across many metrics.
Analytical Tools – Functions for fixture analysis, differential identification, transfer advice, and team rating.
Authentication Support – Secure access to personal team data and manager info.
CLI & Python Module – Flexible ways to launch the server for desktop or development use.

Use cases of Fantasy Premier League

LLM‑powered assistant – Enable Claude or other MCP‑compatible agents to answer fantasy football questions in natural language.
Custom dashboards – Pull data via the fpl:// resources to build real‑time visualizations.
Automated analysis – Schedule the tools (e.g., compare_players) to generate weekly reports.
Transfer recommendations – Combine fixture difficulty and player form to suggest optimal moves.
Research & education – Study player performance trends or simulate fantasy strategies.

FAQ from the Fantasy Premier League

Q: Which Python version is required? A: Python 3.10 or newer.

Q: Can I run the server on mobile devices? A: Mobile support is currently not available; the server is intended for desktop LLM clients.

Q: I get spawn fpl-mcp ENOENT in Claude Desktop. What should I do? A: Use the full path to the executable or, preferably, configure Claude Desktop to run the module with Python as shown above.

Q: How do I store my FPL credentials securely? A: Run fpl-mcp-config setup; the tool saves encrypted credentials in ~/.fpl-mcp/ or lets you create a .env file.

Q: Are write operations (e.g., making transfers) supported? A: Currently only read‑only operations are implemented.

Q: How can I test the server locally? A: Execute python -m fpl_mcp in a terminal and use the MCP Inspector (mcp dev -m fpl_mcp or npx @modelcontextprotocol/inspector python -m fpl_mcp).

Fantasy Premier League MCP Server

A Model Context Protocol (MCP) server that provides access to Fantasy Premier League (FPL) data and tools. This server allows you to interact with FPL data in Claude for Desktop and other MCP-compatible clients.

Demo of the Fantasy Premier League MCP Server in action

Supported Platforms

Claude Desktop
Cursor
Windsurf
Other MCP Compatible Desktop LLMs

Mobile is currently not supported.

Features

Rich Player Data: Access comprehensive player statistics from the FPL API
Team Information: Get details about Premier League teams
Gameweek Data: View current and past gameweek information
Player Search: Find players by name or team
Player Comparison: Compare detailed statistics between any two players

Requirements

Python 3.10 or higher
Claude Desktop (for AI integration)

Installation

Option 1: Install from PyPI (Recommended)

pip install fpl-mcp

Option 1b: Install with Development Dependencies

pip install "fpl-mcp[dev]"

Option 2: Install from GitHub

pip install git+https://github.com/rishijatia/fantasy-pl-mcp.git

Option 3: Clone and Install Locally

git clone https://github.com/rishijatia/fantasy-pl-mcp.git
cd fantasy-pl-mcp
pip install -e .

Running the Server

After installation, you have several options to run the server:

1. Using the CLI command

fpl-mcp

2. Using the Python module

python -m fpl_mcp

3. Using with Claude Desktop

Configure Claude Desktop to use the installed package by editing your claude_desktop_config.json file:

Method 1: Using the Python module directly (most reliable)

{
  "mcpServers": {
    "fantasy-pl": {
      "command": "python",
      "args": ["-m", "fpl_mcp"]
    }
  }
}

Method 2: Using the installed command with full path (if installed with pip)

{
  "mcpServers": {
    "fantasy-pl": {
      "command": "/full/path/to/your/venv/bin/fpl-mcp"
    }
  }
}

Replace /full/path/to/your/venv/bin/fpl-mcp with the actual path to the executable. You can find this by running which fpl-mcp in your terminal after activating your virtual environment.

Note: Using just "command": "fpl-mcp" may result in a spawn fpl-mcp ENOENT error since Claude Desktop might not have access to your virtual environment's PATH. Using the full path or the Python module approach helps avoid this issue.

Usage

In Claude for Desktop

Start Claude for Desktop
You should see FPL tools available via the hammer icon
Example queries:
- "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"

Fantasy-PL MCP Usage Instructions

Basic Commands:

Compare players: "Compare [Player1] and [Player2]"
Find players: "Find players from [Team]" or "Search for [Player Name]"
Fixture difficulty: "Show upcoming fixtures for [Team]"
Captain advice: "Who should I captain between [Player1] and [Player2]?"

Advanced Features:

Statistical analysis: "Compare underlying stats for [Player1] and [Player2]"
Form check: "Show me players in form right now"
Differential picks: "Suggest differentials under 10% ownership"
Team optimization: "Rate my team and suggest transfers"

Tips:

Be specific with player names for accurate results
Include positions when searching (FWD, MID, DEF, GK)
For best captain advice, ask about form, fixtures, and underlying stats
Request comparison of specific metrics (xG, shots in box, etc.

MCP Inspector for Development

For development and testing:

# If you have mcp[cli] installed
mcp dev -m fpl_mcp

# Or use npx
npx @modelcontextprotocol/inspector python -m fpl_mcp

Available Resources

fpl://static/players - All player data with comprehensive statistics
fpl://static/players/{name} - Player data by name search
fpl://static/teams - All Premier League teams
fpl://static/teams/{name} - Team data by name search
fpl://gameweeks/current - Current gameweek data
fpl://gameweeks/all - All gameweeks data
fpl://fixtures - All fixtures for the current season
fpl://fixtures/gameweek/{gameweek_id} - Fixtures for a specific gameweek
fpl://fixtures/team/{team_name} - Fixtures for a specific team
fpl://players/{player_name}/fixtures - Upcoming fixtures for a specific player
fpl://gameweeks/blank - Information about upcoming blank gameweeks
fpl://gameweeks/double - Information about upcoming double gameweeks

Available Tools

get_gameweek_status - Get precise information about current, previous, and next gameweeks
analyze_player_fixtures - Analyze upcoming fixtures for a player with difficulty ratings
get_blank_gameweeks - Get information about upcoming blank gameweeks
get_double_gameweeks - Get information about upcoming double gameweeks
analyze_players - Filter and analyze FPL players based on multiple criteria
analyze_fixtures - Analyze upcoming fixtures for players, teams, or positions
compare_players - Compare multiple players across various metrics
check_fpl_authentication - Check if FPL authentication is working correctly
get_my_team - View your authenticated team (requires authentication)
get_team - View any team with a specific ID (requires authentication)
get_manager_info - Get manager details (requires authentication)

Prompt Templates

player_analysis_prompt - Create a prompt for analyzing an FPL player in depth
transfer_advice_prompt - Get advice on player transfers based on budget and position
team_rating_prompt - Create a prompt for rating and analyzing an FPL team
differential_players_prompt - Create a prompt for finding differential players with low ownership
chip_strategy_prompt - Create a prompt for chip strategy advice

Development

Adding Features

To add new features:

Add resource handlers in the appropriate file within fpl_mcp/fpl/resources/
Add tool handlers in the appropriate file within fpl_mcp/fpl/tools/
Update the __main__.py file to register new resources and tools
Test using the MCP Inspector before deploying to Claude for Desktop

Authentication

To use features requiring authentication (like accessing your team or private leagues), you need to set up your FPL credentials:

# Run the credential setup tool
fpl-mcp-config setup

This interactive tool will:

Prompt for your FPL email, password, and team ID
Let you choose between storing in config.json or .env file
Save credentials securely to ~/.fpl-mcp/

You can test your authentication with:

fpl-mcp-config test

Alternatively, you can manually configure authentication:

Create ~/.fpl-mcp/.env file with:

FPL_EMAIL=your_email@example.com
FPL_PASSWORD=your_password
FPL_TEAM_ID=your_team_id

Or create ~/.fpl-mcp/config.json:

{
  "email": "your_email@example.com",
  "password": "your_password",
  "team_id": "your_team_id"
}

Or set environment variables:

export FPL_EMAIL=your_email@example.com
export FPL_PASSWORD=your_password
export FPL_TEAM_ID=your_team_id

Limitations

The FPL API is not officially documented and may change without notice
Only read operations are currently supported

Troubleshooting

Common Issues

1. "spawn fpl-mcp ENOENT" error in Claude Desktop

This occurs because Claude Desktop cannot find the fpl-mcp executable in its PATH.

Solution: Use one of these approaches:

Use the full path to the executable in your config file

{
  "mcpServers": {
    "fantasy-pl": {
      "command": "/full/path/to/your/venv/bin/fpl-mcp"
    }
  }
}

Use Python to run the module directly (preferred method)

{
  "mcpServers": {
    "fantasy-pl": {
      "command": "python",
      "args": ["-m", "fpl_mcp"]
    }
  }
}

2. Server disconnects immediately

If the server starts but immediately disconnects:

Check logs at ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs\mcp*.log (Windows)
Ensure all dependencies are installed
Try running the server manually with python -m fpl_mcp to see any errors

3. Server not showing in Claude Desktop

If the hammer icon doesn't appear:

Restart Claude Desktop completely
Verify your claude_desktop_config.json has correct JSON syntax
Ensure the path to Python or the executable is absolute, not relative

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

For more details, please refer to the CONTRIBUTING.md file.

Acknowledgments

Fantasy Premier League API for providing the data
Model Context Protocol for the connectivity standard
Claude for the AI assistant capabilities

Citation

If you use this package in your research or project, please consider citing it:

@software{fpl_mcp,
  author = {Jatia, Rishi and Fantasy PL MCP Contributors},
  title = {Fantasy Premier League MCP Server},
  url = {https://github.com/rishijatia/fantasy-pl-mcp},
  version = {0.1.0},
  year = {2025},
}

Fantasy Premier League Overview