fpl-mcp

<div align="center"> <h1><code>fpl-mcp</code></h1> <p>MCP server for the Fantasy Premier League API.</p> <p><i>Query players, teams, fixtures, and your FPL team through any MCP-compatible client.</i></p> </div>

Features

• Player Data — Search, filter, and compare players by stats, price, form, ownership
• Team Analysis — View Premier League team info and strength ratings
• Fixtures — Browse gameweek fixtures, team schedules, and FDR ratings
• Your Team — Fetch your FPL squad (via manager ID or API token)
• Differentials — Find low-ownership, high-form picks
• Auto-caching — Data cached locally with manual refresh option

Prerequisites

• Python 3.11+
• just (command runner)

Installation

git clone https://github.com/yourusername/fpl-mcp.git
cd fpl-mcp

just create-venv
just install

Configuration (optional)

Copy .env.example to .env to configure your manager ID:

cp .env.example .env

# Your FPL manager ID (from URL: fantasy.premierleague.com/entry/XXXXXX/...)
FPL_MANAGER_ID=123456

# Optional: API token for authenticated requests
FPL_API_TOKEN=

Client Setup

Claude Code

Add to ~/.claude/mcp_servers.json:

{
  "fpl-mcp": {
    "command": "/path/to/fpl-mcp/.venv/bin/python",
    "args": ["-m", "src.server"],
    "cwd": "/path/to/fpl-mcp",
    "env": {
      "FPL_MANAGER_ID": "123456"
    }
  }
}

Claude Desktop

Add to Claude Desktop config:

{
  "mcpServers": {
    "fpl-mcp": {
      "command": "/path/to/fpl-mcp/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/fpl-mcp",
      "env": {
        "FPL_MANAGER_ID": "123456"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "fpl-mcp": {
      "command": "/path/to/fpl-mcp/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/fpl-mcp",
      "env": {
        "FPL_MANAGER_ID": "123456"
      }
    }
  }
}

Usage

Command	Description
just info	Show project info
just run	Run the MCP server
just test	Run tests
just lint	Lint with ruff
just fmt	Format with ruff

Tools

Player Tools

Tool	Description
get_player	Get player info by ID
search_player	Search players by name (partial match)
filter_players	Filter by position, team, price, form, points, availability
get_top_players	Rank by metric: points, form, ppg, xG, xA, value
get_differentials	Find low-ownership picks with high form
compare_players	Side-by-side comparison of multiple players

Team Tools

Tool	Description
get_team	Get team info by ID
search_team	Search teams by name
get_all_teams	List all 20 PL teams sorted by strength

Fixture Tools

Tool	Description
get_gameweek_fixtures	All fixtures for a gameweek
get_team_fixtures	Team's fixtures (optionally by gameweek)
get_team_upcoming	Next N fixtures with FDR ratings
get_next_gameweeks	Overview of upcoming gameweeks

Manager Tools

Tool	Description
get_my_team	Fetch your current FPL squad

Utility

Tool	Description
refresh_cache	Force refresh cached FPL data

License

MIT