MCP HubMCP Hub
rishijatia

fantasy-pl-mcp

by: rishijatia

Fantasy Premier League MCP Server

12created 14/03/2025
Visit
Fantasy
Football

📌Overview

Purpose: The Fantasy Premier League MCP Server provides robust access to Fantasy Premier League data and tools for seamless integration with MCP-compatible clients.

Overview: This server offers functionalities to interact with crucial FPL data, enabling users to gather player statistics, team information, and gameweek details, enhancing their decision-making processes for fantasy football.

Key Features:

  • Rich Player Data: Access comprehensive player statistics directly from the FPL API, empowering users to make informed choices based on performance metrics.

  • Team Information: Retrieve detailed insights about Premier League teams, facilitating better understanding and strategies for fantasy leagues.

  • Gameweek Data: Enables viewing of current and past gameweek information, providing context for player and team performances over time.

  • Player Search: Easily find players by name or team, streamlining the process of evaluating potential roster choices.

  • Player Comparison: Compare detailed statistics between any two players to analyze their performance and suitability for one's fantasy team.

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.

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

  1. Start Claude for Desktop
  2. 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

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

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

Authentication

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

fpl-mcp-config setup

This interactive tool will prompt for your FPL email, password, and team ID, then let you choose to store credentials securely.

Test your authentication with:

fpl-mcp-config test

Alternatively, 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

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

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

Solution:

  • Use full path to the executable in config file:

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

  • Or use Python module directly:

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

2. Server disconnects immediately

  • Check logs at ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs\mcp*.log (Windows)
  • Ensure all dependencies are installed
  • Run server manually with python -m fpl_mcp to check for errors

3. Server not showing in Claude Desktop

  • Restart Claude Desktop completely
  • Verify claude_desktop_config.json has correct JSON syntax
  • Use absolute paths for Python or executable configurations

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please submit a Pull Request.

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

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},
}