Fantasy Premier League MCP server for AI agents

The Fantasy Premier League MCP server provides access to FPL data and tools through the Model Context Protocol (MCP), allowing you to interact with comprehensive fantasy football information in Claude for Desktop and other MCP-compatible clients.

Installation

Install from PyPI (Recommended)

pip install fpl-mcp

Install with Development Dependencies

pip install "fpl-mcp[dev]"

Install from GitHub

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

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 can run the server using any of these methods:

Using the CLI Command

fpl-mcp

Using the Python Module

python -m fpl_mcp

Configuring with Claude Desktop

Edit your claude_desktop_config.json file using one of these methods:

Method 1: Using the Python Module (Most Reliable)

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

Method 2: Using Full Path to Executable

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

Find the full path by running which fpl-mcp in your terminal after activating your virtual environment.

Authentication

To use features requiring authentication (like accessing your team):

fpl-mcp-config setup

This interactive tool will guide you through setting up your FPL credentials.

Alternatively, manually configure authentication by creating one of these:

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

[email protected]
FPL_PASSWORD=your_password
FPL_TEAM_ID=your_team_id

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

{
  "email": "[email protected]",
  "password": "your_password",
  "team_id": "your_team_id"
}

Or set environment variables:

export [email protected]
export FPL_PASSWORD=your_password
export FPL_TEAM_ID=your_team_id

Test your authentication with:

fpl-mcp-config test

Usage in Claude Desktop

Once configured, start Claude Desktop and 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"

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)

Troubleshooting

"spawn fpl-mcp ENOENT" Error

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

Solution: Use one of these approaches:

Use the full path to the executable in your config file
Use Python to run the module directly (preferred method)

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

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "fantasy-pl" '{"command":"python","args":["-m","fpl_mcp"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect