fpl-mcp-server

ShayKorin/fpl-mcp-server

3.1

If you are the rightful owner of fpl-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The FPL MCP Server is a comprehensive Model Context Protocol server designed for Fantasy Premier League analysis, offering advanced tools for team optimization, player analysis, and strategic planning.

Tools
4
Resources
0
Prompts
0

FPL MCP Server 🏆

A comprehensive Model Context Protocol (MCP) server for Fantasy Premier League analysis, providing advanced tools for team optimization, player analysis, and strategic planning.

Features ✨

Complete v1.0 Analytics Platform

26 comprehensive tools providing advanced Fantasy Premier League analysis:

🔍 Core Data Tools (4 tools)
  • Data Access: Bootstrap data, player summaries, search, fixtures
  • Foundation: Essential FPL data for all analysis
🏟️ Phase 1: Team Analysis (5 tools)
  • Team Management: Get picks, history, transfers for any FPL team
  • Live Tracking: Real-time gameweek data and bonus points
  • Dream Team: Official FPL dream team analysis
👤 Phase 2: Player Analytics (17 tools)
  • Form Analysis: Detailed consistency and performance metrics
  • Fixture Intelligence: Upcoming fixture difficulty analysis
  • Market Intelligence: Differential picks, value analysis, price predictions
  • Specialist Analysis: Penalty takers, set piece specialists, rotation risk
  • Performance Insights: Expected stats, breakout candidates, bonus points
🔧 Core Infrastructure
  • 💾 Smart Caching: Redis + memory fallback for optimal performance
  • 🔐 Team ID Authentication: Advanced FPL community practices
  • 📊 Rich Data Processing: Comprehensive FPL API coverage
  • ⚡ Real-time Analysis: Live gameweek data and bonus tracking

Architecture Highlights

  • 🚀 FastMCP Framework: Modern MCP implementation with 26 tools
  • 🔐 Authentication Support: Team ID approach for advanced users
  • ⚡ Intelligent Caching: Redis backend with memory fallback
  • 🛡️ Error Handling: Comprehensive retry logic and graceful degradation
  • 📝 Rich Logging: Beautiful console output with detailed information
  • 🎯 Advanced Analytics: Professional-grade FPL analysis tools

Quick Start 🚀

Prerequisites

  • Python 3.11+
  • Claude Desktop

Installation

  1. Clone and Setup:
cd ~/projects/fpl-mcp-server
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
  1. Configure Claude Desktop: Add to ~/.config/claude-code/claude_desktop_config.json:
{
  "mcpServers": {
    "fpl-advanced": {
      "command": "/Users/shayko/projects/fpl-mcp-server/venv/bin/python",
      "args": ["-m", "fpl_mcp.server"],
      "cwd": "/Users/shayko/projects/fpl-mcp-server/src"
    }
  }
}
  1. Optional - Configure Authentication: Copy .env.example to .env and add your FPL credentials:
cp .env.example .env
# Edit .env with your FPL_EMAIL and FPL_PASSWORD
  1. Test Installation:
python test_server.py

Available Tools 🛠️

🔍 Core Data Tools

get_bootstrap_data()

Get FPL bootstrap static data including all players, teams, and game settings. Returns: Season overview with total players, teams, current gameweek, and deadline information.

get_player_summary(player_id: int)

Get detailed summary for a specific player including fixtures and historical data. Returns: Season performance, recent form, and upcoming fixtures.

search_players(name: str, position?: str, max_price?: float)

Search for players by name with optional filters. Returns: List of matching players with stats and prices.

get_fixtures(gameweek?: int)

Get fixture information for current or specific gameweek. Returns: Fixture list with teams, dates, and kickoff times.

🏟️ Phase 1: Core Team Analysis (15 Tools)

Team Management
  • get_team_picks(team_id: int, gameweek: int) - Get team lineup with captain info
  • get_team_history(team_id: int) - Complete team performance history
  • get_team_transfers(team_id: int) - All transfers with costs and timing
Live Tracking
  • get_live_gameweek_data(gameweek?: int) - Real-time scores and bonus points
  • get_dream_team(gameweek: int) - Official FPL dream team with top performers

👤 Phase 2: Advanced Player Analytics (18 Tools)

Form & Performance Analysis
  • get_player_form_analysis(player_id: int, gameweeks?: int) - Detailed form metrics
  • get_player_consistency_analysis(player_id: int, gameweeks?: int) - Consistency and variance
  • get_expected_stats_analysis(player_id: int) - xG/xA vs actual performance
  • get_bonus_points_analysis(gameweek?: int) - BPS leaders and bonus distribution
Strategic Intelligence
  • get_player_fixture_analysis(player_id: int, gameweeks_ahead?: int) - Fixture difficulty
  • get_rotation_risk_analysis(team_id: int) - Player rotation risk by team
  • get_player_minutes_risk(threshold_percentage?: float) - Minutes decline analysis
Market Intelligence
  • get_differential_picks(max_ownership?: float, min_points?: int) - Low ownership gems
  • get_form_players(gameweeks?: int, position?: str) - Players in best form
  • get_value_picks(max_price: float, position?: str) - Best value by price
  • get_price_change_predictions() - Likely price rises and falls
  • get_ownership_stats(gameweek?: int) - Template vs differential players
Specialist Analysis
  • get_penalty_takers() - Current penalty takers by team
  • get_set_piece_takers() - Corner and free kick specialists
  • get_captaincy_analysis(gameweek?: int) - Top captain candidates
  • get_breakout_candidates(max_price?: float, min_games?: int) - Emerging talent
  • get_underperforming_premiums(min_price?: float) - Premium players due returns

🎯 Example Usage

Find differential captain options:

> Get differential picks with max 5% ownership
> Get captaincy analysis for gameweek 15

Analyze team rotation:

> Get rotation risk analysis for team 1 (Arsenal)
> Get player minutes risk with 70% threshold

Market intelligence:

> Get price change predictions
> Get value picks under £6.5m for midfielders

Advanced Configuration ⚙️

Environment Variables

# FPL Authentication (optional)
FPL_EMAIL=your_email@example.com
FPL_PASSWORD=your_password

# Cache Settings
CACHE_TTL_SECONDS=300
REDIS_HOST=localhost
REDIS_PORT=6379

# Performance
REQUEST_TIMEOUT=30
MAX_RETRIES=3

# Logging
LOG_LEVEL=INFO
ENABLE_DEBUG=false

Redis Setup (Optional)

For improved performance with Redis caching:

# macOS with Homebrew
brew install redis
brew services start redis

# Verify Redis is running
redis-cli ping

Development 👨‍💻

Testing

# Run basic functionality test
python test_server.py

# Run with debug logging
LOG_LEVEL=DEBUG python test_server.py

Adding New Tools

  1. Add tool function to src/fpl_mcp/server.py
  2. Use @mcp.tool() decorator
  3. Follow existing patterns for error handling and caching

Project Structure

fpl-mcp-server/
├── src/fpl_mcp/
│   ├── server.py           # Main MCP server
│   ├── api/client.py       # FPL API client
│   ├── cache/manager.py    # Cache management
│   └── utils/config.py     # Configuration
├── tests/                  # Test files
├── requirements.txt        # Dependencies
└── README.md              # This file

Troubleshooting 🔧

Common Issues

"FPL client not initialized"

  • Ensure the server started properly
  • Check logs for initialization errors

"Redis unavailable"

  • Normal behavior if Redis isn't installed
  • Server will use memory caching instead

"Request failed after X attempts"

  • Check internet connection
  • FPL API might be temporarily unavailable

Getting Help

  • Check server logs for detailed error information
  • Enable debug mode: LOG_LEVEL=DEBUG
  • Test basic functionality with python test_server.py

Roadmap 🗺️

✅ v1.0.0 Complete - Advanced FPL Analytics Platform

  • ✅ 33 Comprehensive Tools: Team analysis, player analytics, market intelligence
  • ✅ Live Tracking: Real-time bonus points and player performance
  • ✅ Market Intelligence: Ownership trends, price predictions, differentials
  • ✅ Specialist Analysis: Penalty takers, set piece specialists, rotation risk
  • ✅ Performance Analytics: Form analysis, expected stats, consistency metrics

🚀 Planned v2.0 Features

  • 🤖 Team Optimization: Mathematical team selection algorithms using linear programming
  • 🧠 ML Predictions: Machine learning models for player performance forecasting
  • 🏆 League Management: H2H analysis, competitor tracking, and mini-league insights
  • 💡 Chip Strategy: Optimal timing algorithms for wildcard, bench boost, triple captain
  • 📈 Advanced Modeling: xG/xA modeling, fixture difficulty algorithms, variance analysis

🔮 Future Enhancements

  • 🌍 Multi-League Support: Champions League, Premier League, international tournaments
  • 📊 Historical Deep Dive: Multi-season trends, player lifecycle analysis
  • 🎯 Custom Strategies: User-defined scoring systems and strategy templates
  • 📱 Integration APIs: Connect with external FPL tools and mobile apps

License 📄

This project is for educational and personal use. Please respect FPL's terms of service.

Built with ❤️ for the FPL community using Claude Code