# Fantasy Premier League MCP Server
[](https://badge.fury.io/py/fpl-mcp)
[](https://github.com/rishijatia/fantasy-pl-mcp/actions/workflows/package-check.yml)
[](https://pypi.org/project/fpl-mcp/)
[](https://opensource.org/licenses/MIT)
[](https://pepy.tech/project/fpl-mcp)
<a href="https://glama.ai/mcp/servers/2zxsxuxuj9">
<img width="380" height="200" src="https://glama.ai/mcp/servers/2zxsxuxuj9/badge" />
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*
[](https://youtu.be/QfOOOQ_jeMA)
## 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)
```bash
pip install fpl-mcp
```
### Option 1b: Install with Development Dependencies
```bash
pip install "fpl-mcp[dev]"
```
### Option 2: Install from GitHub
```bash
pip install git+https://github.com/rishijatia/fantasy-pl-mcp.git
```
### Option 3: Clone and Install Locally
```bash
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
```bash
fpl-mcp
```
### 2. Using the Python module
```bash
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)**
```json
{
"mcpServers": {
"fantasy-pl": {
"command": "python",
"args": ["-m", "fpl_mcp"]
}
}
}
```
**Method 2: Using the installed command with full path (if installed with pip)**
```json
{
"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
3. 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:
```bash
# 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:
1. Add resource handlers in the appropriate file within `fpl_mcp/fpl/resources/`
2. Add tool handlers in the appropriate file within `fpl_mcp/fpl/tools/`
3. Update the `__main__.py` file 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), you need to set up your FPL credentials:
```bash
# Run the credential setup tool
fpl-mcp-config setup
```
This interactive tool will:
1. Prompt for your FPL email, password, and team ID
2. Let you choose between storing in config.json or .env file
3. Save credentials securely to ~/.fpl-mcp/
You can test your authentication with:
```bash
fpl-mcp-config test
```
Alternatively, you can manually configure authentication:
1. Create `~/.fpl-mcp/.env` file with:
```
FPL_EMAIL=your_email@example.com
FPL_PASSWORD=your_password
FPL_TEAM_ID=your_team_id
```
2. Or create `~/.fpl-mcp/config.json`:
```json
{
"email": "your_email@example.com",
"password": "your_password",
"team_id": "your_team_id"
}
```
3. Or set environment variables:
```bash
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
```json
{
"mcpServers": {
"fantasy-pl": {
"command": "/full/path/to/your/venv/bin/fpl-mcp"
}
}
}
```
- Use Python to run the module directly (preferred method)
```json
{
"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.
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
For more details, please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) file.
## Acknowledgments
- [Fantasy Premier League API](https://fantasy.premierleague.com/api/) for providing the data
- [Model Context Protocol](https://modelcontextprotocol.io/) for the connectivity standard
- [Claude](https://claude.ai/) for the AI assistant capabilities
## Citation
If you use this package in your research or project, please consider citing it:
```bibtex
@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},
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/rishijatia/fantasy-pl-mcp",
"name": "fpl-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "fantasy-premier-league, fpl, mcp, claude, ai, football, soccer",
"author": "Fantasy PL MCP Contributors",
"author_email": "Fantasy PL MCP Contributors <rishi.jatia96@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/46/50/3de589eb2f4fcf775085d370db6609550ea8c5af2f0846e9c59e583e6ab5/fpl_mcp-0.1.6.tar.gz",
"platform": null,
"description": "# Fantasy Premier League MCP Server\n\n[](https://badge.fury.io/py/fpl-mcp)\n[](https://github.com/rishijatia/fantasy-pl-mcp/actions/workflows/package-check.yml)\n[](https://pypi.org/project/fpl-mcp/)\n[](https://opensource.org/licenses/MIT)\n[](https://pepy.tech/project/fpl-mcp)\n<a href=\"https://glama.ai/mcp/servers/2zxsxuxuj9\">\n <img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/2zxsxuxuj9/badge\" />\n\nA 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.\n\n*Demo of the Fantasy Premier League MCP Server in action*\n\n[](https://youtu.be/QfOOOQ_jeMA)\n\n\n## Supported Platforms\n\n- Claude Desktop\n- Cursor\n- Windsurf\n- Other MCP Compatible Desktop LLMs\n\nMobile is currently not supported.\n\n## Features\n\n- **Rich Player Data**: Access comprehensive player statistics from the FPL API\n- **Team Information**: Get details about Premier League teams\n- **Gameweek Data**: View current and past gameweek information\n- **Player Search**: Find players by name or team\n- **Player Comparison**: Compare detailed statistics between any two players\n\n## Requirements\n\n- Python 3.10 or higher\n- Claude Desktop (for AI integration)\n\n## Installation\n\n### Option 1: Install from PyPI (Recommended)\n\n```bash\npip install fpl-mcp\n```\n\n### Option 1b: Install with Development Dependencies\n\n```bash\npip install \"fpl-mcp[dev]\"\n```\n\n### Option 2: Install from GitHub\n\n```bash\npip install git+https://github.com/rishijatia/fantasy-pl-mcp.git\n```\n\n### Option 3: Clone and Install Locally\n\n```bash\ngit clone https://github.com/rishijatia/fantasy-pl-mcp.git\ncd fantasy-pl-mcp\npip install -e .\n```\n\n## Running the Server\n\nAfter installation, you have several options to run the server:\n\n### 1. Using the CLI command\n\n```bash\nfpl-mcp\n```\n\n### 2. Using the Python module\n\n```bash\npython -m fpl_mcp\n```\n\n### 3. Using with Claude Desktop\n\nConfigure Claude Desktop to use the installed package by editing your `claude_desktop_config.json` file:\n\n**Method 1: Using the Python module directly (most reliable)**\n\n```json\n{\n \"mcpServers\": {\n \"fantasy-pl\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"fpl_mcp\"]\n }\n }\n}\n```\n\n**Method 2: Using the installed command with full path (if installed with pip)**\n\n```json\n{\n \"mcpServers\": {\n \"fantasy-pl\": {\n \"command\": \"/full/path/to/your/venv/bin/fpl-mcp\"\n }\n }\n}\n```\n\nReplace `/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.\n\n> **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.\n\n## Usage\n\n### In Claude for Desktop\n\n1. Start Claude for Desktop\n2. You should see FPL tools available via the hammer icon\n3. Example queries:\n - \"Compare Mohamed Salah and Erling Haaland over the last 5 gameweeks\"\n - \"Find all Arsenal midfielders\"\n - \"What's the current gameweek status?\"\n - \"Show me the top 5 forwards by points\"\n\n#### Fantasy-PL MCP Usage Instructions\n\n#### Basic Commands:\n- Compare players: \"Compare [Player1] and [Player2]\"\n- Find players: \"Find players from [Team]\" or \"Search for [Player Name]\"\n- Fixture difficulty: \"Show upcoming fixtures for [Team]\"\n- Captain advice: \"Who should I captain between [Player1] and [Player2]?\"\n\n#### Advanced Features:\n- Statistical analysis: \"Compare underlying stats for [Player1] and [Player2]\"\n- Form check: \"Show me players in form right now\"\n- Differential picks: \"Suggest differentials under 10% ownership\"\n- Team optimization: \"Rate my team and suggest transfers\"\n\n#### Tips:\n- Be specific with player names for accurate results\n- Include positions when searching (FWD, MID, DEF, GK)\n- For best captain advice, ask about form, fixtures, and underlying stats\n- Request comparison of specific metrics (xG, shots in box, etc. \n\n### MCP Inspector for Development\n\nFor development and testing:\n\n```bash\n# If you have mcp[cli] installed\nmcp dev -m fpl_mcp\n\n# Or use npx\nnpx @modelcontextprotocol/inspector python -m fpl_mcp\n```\n\n## Available Resources\n- `fpl://static/players` - All player data with comprehensive statistics\n- `fpl://static/players/{name}` - Player data by name search\n- `fpl://static/teams` - All Premier League teams\n- `fpl://static/teams/{name}` - Team data by name search\n- `fpl://gameweeks/current` - Current gameweek data\n- `fpl://gameweeks/all` - All gameweeks data\n- `fpl://fixtures` - All fixtures for the current season\n- `fpl://fixtures/gameweek/{gameweek_id}` - Fixtures for a specific gameweek\n- `fpl://fixtures/team/{team_name}` - Fixtures for a specific team\n- `fpl://players/{player_name}/fixtures` - Upcoming fixtures for a specific player\n- `fpl://gameweeks/blank` - Information about upcoming blank gameweeks\n- `fpl://gameweeks/double` - Information about upcoming double gameweeks\n\n## Available Tools\n- `get_gameweek_status` - Get precise information about current, previous, and next gameweeks\n- `analyze_player_fixtures` - Analyze upcoming fixtures for a player with difficulty ratings\n- `get_blank_gameweeks` - Get information about upcoming blank gameweeks\n- `get_double_gameweeks` - Get information about upcoming double gameweeks\n- `analyze_players` - Filter and analyze FPL players based on multiple criteria\n- `analyze_fixtures` - Analyze upcoming fixtures for players, teams, or positions\n- `compare_players` - Compare multiple players across various metrics\n- `check_fpl_authentication` - Check if FPL authentication is working correctly\n- `get_my_team` - View your authenticated team (requires authentication)\n- `get_team` - View any team with a specific ID (requires authentication)\n- `get_manager_info` - Get manager details (requires authentication)\n\n## Prompt Templates\n- `player_analysis_prompt` - Create a prompt for analyzing an FPL player in depth\n- `transfer_advice_prompt` - Get advice on player transfers based on budget and position\n- `team_rating_prompt` - Create a prompt for rating and analyzing an FPL team\n- `differential_players_prompt` - Create a prompt for finding differential players with low ownership\n- `chip_strategy_prompt` - Create a prompt for chip strategy advice\n\n## Development\n\n### Adding Features\n\nTo add new features:\n\n1. Add resource handlers in the appropriate file within `fpl_mcp/fpl/resources/`\n2. Add tool handlers in the appropriate file within `fpl_mcp/fpl/tools/`\n3. Update the `__main__.py` file to register new resources and tools\n4. Test using the MCP Inspector before deploying to Claude for Desktop\n\n## Authentication\n\nTo use features requiring authentication (like accessing your team or private leagues), you need to set up your FPL credentials:\n\n```bash\n# Run the credential setup tool\nfpl-mcp-config setup\n```\n\nThis interactive tool will:\n1. Prompt for your FPL email, password, and team ID\n2. Let you choose between storing in config.json or .env file\n3. Save credentials securely to ~/.fpl-mcp/\n\nYou can test your authentication with:\n```bash\nfpl-mcp-config test\n```\n\nAlternatively, you can manually configure authentication:\n1. Create `~/.fpl-mcp/.env` file with:\n ```\n FPL_EMAIL=your_email@example.com\n FPL_PASSWORD=your_password\n FPL_TEAM_ID=your_team_id\n ```\n \n2. Or create `~/.fpl-mcp/config.json`:\n ```json\n {\n \"email\": \"your_email@example.com\",\n \"password\": \"your_password\",\n \"team_id\": \"your_team_id\"\n }\n ```\n\n3. Or set environment variables:\n ```bash\n export FPL_EMAIL=your_email@example.com\n export FPL_PASSWORD=your_password\n export FPL_TEAM_ID=your_team_id\n ```\n\n## Limitations\n\n- The FPL API is not officially documented and may change without notice\n- Only read operations are currently supported\n\n## Troubleshooting\n\n### Common Issues\n\n#### 1. \"spawn fpl-mcp ENOENT\" error in Claude Desktop\n\nThis occurs because Claude Desktop cannot find the `fpl-mcp` executable in its PATH.\n\n**Solution:** Use one of these approaches:\n\n- Use the full path to the executable in your config file\n ```json\n {\n \"mcpServers\": {\n \"fantasy-pl\": {\n \"command\": \"/full/path/to/your/venv/bin/fpl-mcp\"\n }\n }\n }\n ```\n\n- Use Python to run the module directly (preferred method)\n ```json\n {\n \"mcpServers\": {\n \"fantasy-pl\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"fpl_mcp\"]\n }\n }\n }\n ```\n\n#### 2. Server disconnects immediately\n\nIf the server starts but immediately disconnects:\n\n- Check logs at `~/Library/Logs/Claude/mcp*.log` (macOS) or `%APPDATA%\\Claude\\logs\\mcp*.log` (Windows)\n- Ensure all dependencies are installed\n- Try running the server manually with `python -m fpl_mcp` to see any errors\n\n#### 3. Server not showing in Claude Desktop\n\nIf the hammer icon doesn't appear:\n\n- Restart Claude Desktop completely\n- Verify your `claude_desktop_config.json` has correct JSON syntax\n- Ensure the path to Python or the executable is absolute, not relative\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nFor more details, please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) file.\n\n## Acknowledgments\n\n- [Fantasy Premier League API](https://fantasy.premierleague.com/api/) for providing the data\n- [Model Context Protocol](https://modelcontextprotocol.io/) for the connectivity standard\n- [Claude](https://claude.ai/) for the AI assistant capabilities\n\n## Citation\n\nIf you use this package in your research or project, please consider citing it:\n\n```bibtex\n@software{fpl_mcp,\n author = {Jatia, Rishi and Fantasy PL MCP Contributors},\n title = {Fantasy Premier League MCP Server},\n url = {https://github.com/rishijatia/fantasy-pl-mcp},\n version = {0.1.0},\n year = {2025},\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An MCP server for Fantasy Premier League data",
"version": "0.1.6",
"project_urls": {
"Homepage": "https://github.com/rishijatia/fantasy-pl-mcp",
"Issues": "https://github.com/rishijatia/fantasy-pl-mcp/issues"
},
"split_keywords": [
"fantasy-premier-league",
" fpl",
" mcp",
" claude",
" ai",
" football",
" soccer"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "97f74553d3cb34546bd8b784398c50dccfe695d904a6faa5c6279c1d2179331c",
"md5": "855da3a93a30765670d58c7519b023aa",
"sha256": "c4fe0354cd8395f88e108cce46ac0510ef012be76f097a1bfbb214d9f8f480ef"
},
"downloads": -1,
"filename": "fpl_mcp-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "855da3a93a30765670d58c7519b023aa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 68279,
"upload_time": "2025-07-31T22:33:29",
"upload_time_iso_8601": "2025-07-31T22:33:29.036698Z",
"url": "https://files.pythonhosted.org/packages/97/f7/4553d3cb34546bd8b784398c50dccfe695d904a6faa5c6279c1d2179331c/fpl_mcp-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "46503de589eb2f4fcf775085d370db6609550ea8c5af2f0846e9c59e583e6ab5",
"md5": "07a320954f3a575ad0d29492c4b2a6ee",
"sha256": "201bcecd17d5d3e94eaa9d705d87f5fc8185da415462bbfb48055d16f7470a16"
},
"downloads": -1,
"filename": "fpl_mcp-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "07a320954f3a575ad0d29492c4b2a6ee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 65624,
"upload_time": "2025-07-31T22:33:30",
"upload_time_iso_8601": "2025-07-31T22:33:30.267296Z",
"url": "https://files.pythonhosted.org/packages/46/50/3de589eb2f4fcf775085d370db6609550ea8c5af2f0846e9c59e583e6ab5/fpl_mcp-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 22:33:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rishijatia",
"github_project": "fantasy-pl-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fpl-mcp"
}
JSON
