Fantasy Premier League

Acesse dados e ferramentas do Fantasy Premier League (FPL), incluindo informações de jogadores, detalhes de times e dados de rodadas.

GitHub
76
Experimente este MCPPatrocinado

Documentação

Servidor MCP do Fantasy Premier League

PyPI version Package Check PyPI - Python Version License: MIT Downloads

Trust Score

Um servidor Model Context Protocol (MCP) que fornece acesso a dados e ferramentas do Fantasy Premier League (FPL). Este servidor permite que você interaja com dados do FPL no Claude for Desktop e em outros clientes compatíveis com MCP.

Demonstração do servidor MCP do Fantasy Premier League em ação

Fantasy Premier League MCP Demo

Plataformas Suportadas

  • Claude Desktop
  • Cursor
  • Windsurf
  • Outros LLMs de Desktop compatíveis com MCP

Dispositivos móveis não são suportados atualmente.

Recursos

  • Dados Ricos de Jogadores: Acesse estatísticas abrangentes de jogadores da API do FPL
  • Informações de Times: Obtenha detalhes sobre os times da Premier League
  • Dados de Rodadas: Veja informações de rodadas atuais e passadas
  • Busca de Jogadores: Encontre jogadores por nome ou time
  • Comparação de Jogadores: Compare estatísticas detalhadas entre quaisquer dois jogadores

Requisitos

  • Python 3.10 ou superior
  • Claude Desktop (para integração com IA)

Instalação

Opção 1: Instalar a partir do PyPI (Recomendado)

pip install fpl-mcp

Opção 1b: Instalar com Dependências de Desenvolvimento

pip install "fpl-mcp[dev]"

Opção 2: Instalar a partir do GitHub

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

Opção 3: Clonar e Instalar Localmente

git clone https://github.com/rishijatia/fantasy-pl-mcp.git
cd fantasy-pl-mcp
pip install -e .

Executando o Servidor

Após a instalação, você tem várias opções para executar o servidor:

1. Usando o comando CLI

fpl-mcp

2. Usando o módulo Python

python -m fpl_mcp

3. Usando com o Claude Desktop

Configure o Claude Desktop para usar o pacote instalado editando seu arquivo claude_desktop_config.json:

Método 1: Usando o módulo Python diretamente (mais confiável)

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

Método 2: Usando o comando instalado com caminho completo (se instalado com pip)

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

Substitua /full/path/to/your/venv/bin/fpl-mcp pelo caminho real para o executável. Você pode encontrá-lo executando which fpl-mcp no seu terminal após ativar seu ambiente virtual.

Nota: Usar apenas "command": "fpl-mcp" pode resultar em um erro spawn fpl-mcp ENOENT já que o Claude Desktop pode não ter acesso ao PATH do seu ambiente virtual. Usar o caminho completo ou a abordagem do módulo Python ajuda a evitar esse problema.

Uso

No Claude for Desktop

  1. Inicie o Claude for Desktop
  2. Você deve ver as ferramentas do FPL disponíveis via o ícone de martelo
  3. Exemplos de consultas:
    • "Compare Mohamed Salah e Erling Haaland nas últimas 5 rodadas"
    • "Encontre todos os meio-campistas do Arsenal"
    • "Qual é o status da rodada atual?"
    • "Mostre os 5 melhores atacantes por pontos"

Instruções de Uso do Fantasy-PL MCP

Comandos Básicos:

  • Comparar jogadores: "Compare [Jogador1] e [Jogador2]"
  • Encontrar jogadores: "Encontre jogadores do [Time]" ou "Busque por [Nome do Jogador]"
  • Dificuldade dos jogos: "Mostre os próximos jogos do [Time]"
  • Conselho de capitão: "Quem devo colocar como capitão entre [Jogador1] e [Jogador2]?"

Recursos Avançados:

  • Análise estatística: "Compare estatísticas subjacentes de [Jogador1] e [Jogador2]"
  • Verificação de forma: "Mostre jogadores em boa fase agora"
  • Escolhas diferenciais: "Sugira diferenciais com menos de 10% de propriedade"
  • Otimização de time: "Avalie meu time e sugira transferências"

Dicas:

  • Seja específico com os nomes dos jogadores para resultados precisos
  • Inclua posições ao pesquisar (ATA, MEI, ZAG, GOL)
  • Para o melhor conselho de capitão, pergunte sobre forma, jogos e estatísticas subjacentes
  • Solicite comparação de métricas específicas (xG, chutes na área, etc.

MCP Inspector para Desenvolvimento

Para desenvolvimento e testes:

# If you have mcp[cli] installed
mcp dev -m fpl_mcp

# Or use npx
npx @modelcontextprotocol/inspector python -m fpl_mcp

Recursos Disponíveis

  • fpl://static/players - Todos os dados de jogadores com estatísticas abrangentes
  • fpl://static/players/{name} - Dados de jogadores por busca de nome
  • fpl://static/teams - Todos os times da Premier League
  • fpl://static/teams/{name} - Dados de times por busca de nome
  • fpl://gameweeks/current - Dados da rodada atual
  • fpl://gameweeks/all - Dados de todas as rodadas
  • fpl://fixtures - Todos os jogos da temporada atual
  • fpl://fixtures/gameweek/{gameweek_id} - Jogos de uma rodada específica
  • fpl://fixtures/team/{team_name} - Jogos de um time específico
  • fpl://players/{player_name}/fixtures - Próximos jogos de um jogador específico
  • fpl://gameweeks/blank - Informações sobre próximas rodadas em branco
  • fpl://gameweeks/double - Informações sobre próximas rodadas duplas

Ferramentas Disponíveis

Jogadores

  • search_fpl_players - Busque jogadores por nome, com filtros opcionais de posição e time
  • get_player_information - Obtenha informações detalhadas e histórico de rodadas de um jogador
  • analyze_players - Filtre e analise jogadores do FPL com base em múltiplos critérios
  • compare_players - Compare múltiplos jogadores em várias métricas
  • get_price_changes - Obtenha jogadores cujo preço subiu ou caiu na rodada atual

Jogos e Rodadas

  • get_gameweek_status - Obtenha informações precisas sobre rodadas atuais, anteriores e próximas
  • analyze_player_fixtures - Analise os próximos jogos de um jogador com classificações de dificuldade
  • analyze_fixtures - Analise os próximos jogos de jogadores, times ou posições
  • get_blank_gameweeks - Obtenha informações sobre próximas rodadas em branco
  • get_double_gameweeks - Obtenha informações sobre próximas rodadas duplas

Rodada ao Vivo

  • get_gameweek_live_scores - Pontos e estatísticas ao vivo dos jogadores durante as partidas
  • get_dream_team - O XI oficial com maior pontuação de uma rodada

Seu Time e Conselhos

  • suggest_captain - Classifique seu elenco por pontuação de capitão com raciocínio por componente
  • check_fpl_authentication - Verifique se a autenticação do FPL está funcionando corretamente
  • update_fpl_credentials - Atualize suas credenciais FPL armazenadas a partir de um chat
  • get_my_team - Veja seu time autenticado (requer autenticação)
  • get_my_current_team - Veja seu time atual para a rodada ativa (requer autenticação)
  • get_team - Veja qualquer time com um ID específico (requer autenticação)
  • get_manager - Obtenha detalhes do técnico para um ID de time específico (requer autenticação)
  • get_manager_info - Obtenha detalhes do técnico (requer autenticação)
  • get_manager_transfer_history - Obtenha o histórico completo de transferências de um técnico

Ligas

  • get_league_standings - Obtenha a classificação de uma liga clássica (requer autenticação)
  • get_league_analytics - Analise os técnicos de uma liga, tendências de propriedade e desempenho

Modelos de Prompt

  • player_analysis_prompt - Crie um prompt para analisar um jogador do FPL em profundidade
  • transfer_advice_prompt - Obtenha conselhos sobre transferências de jogadores com base no orçamento e posição
  • team_rating_prompt - Crie um prompt para avaliar e analisar um time do FPL
  • differential_players_prompt - Crie um prompt para encontrar jogadores diferenciais com baixa propriedade
  • chip_strategy_prompt - Crie um prompt para conselhos de estratégia de chips

Desenvolvimento

Adicionando Recursos

Para adicionar novos recursos:

  1. Adicione manipuladores de recursos no arquivo apropriado dentro de fpl_mcp/fpl/resources/
  2. Adicione manipuladores de ferramentas no arquivo apropriado dentro de fpl_mcp/fpl/tools/
  3. Atualize o arquivo __main__.py para registrar novos recursos e ferramentas
  4. Teste usando o MCP Inspector antes de implantar no Claude for Desktop

Autenticação

O FPL migrou seu login para o PingOne (Ping Identity) OIDC, então a autenticação agora usa um token de atualização OIDC em vez do seu e-mail e senha. O token de atualização é trocado automaticamente por tokens de acesso de curta duração, e as solicitações são enviadas com um cabeçalho X-API-Authorization: Bearer.

Para usar recursos que exigem autenticação (como acessar seu time ou ligas privadas), configure seu token de atualização:

# Run the credential setup tool
fpl-mcp-config setup

Esta ferramenta interativa irá:

  1. Mostrar como copiar seu token de atualização OIDC do navegador
  2. Solicitar o token de atualização e o ID do seu time
  3. Salvá-los (criptografados) em ~/.fpl-mcp/credentials.enc

Obtendo seu token de atualização:

  1. Faça login em https://fantasy.premierleague.com no seu navegador.
  2. Abra o Console do DevTools (F12 → Console) e execute: 
    copy(JSON.parse(localStorage.getItem(Object.keys(localStorage).find(k=>k.startsWith('oidc.user:')))).refresh_token)
    (Se o Chrome recusar, digite allow pasting no console primeiro.) O token de atualização agora está na sua área de transferência — cole-o quando solicitado.
  3. Alternativamente: DevTools → Application → Local storage → https://fantasy.premierleague.com, copie todo o valor JSON da chave começando com oidc.user: e cole-o — a configuração extrai o campo refresh_token automaticamente.

Execute fpl-mcp-config test logo após a configuração: a primeira troca reivindica o token antes que sua sessão do navegador possa substituí-lo, e o rotaciona para que a cópia no seu navegador seja aposentada — isso é esperado, e sua sessão do navegador se recupera sozinha.

Você pode testar sua autenticação com:

fpl-mcp-config test

Alternativamente, você pode configurar a autenticação manualmente:

  1. Crie o arquivo ~/.fpl-mcp/.env com:

    FPL_REFRESH_TOKEN=your_refresh_token
FPL_TEAM_ID=your_team_id

  2. Ou crie ~/.fpl-mcp/config.json:

    {
  "refresh_token": "your_refresh_token",
  "team_id": "your_team_id"
}

  3. Ou defina variáveis de ambiente:

    export FPL_REFRESH_TOKEN=your_refresh_token
export FPL_TEAM_ID=your_team_id

Nota: tokens de atualização podem ser rotacionados ou revogados pelo FPL. Se a autenticação começar a falhar, execute novamente fpl-mcp-config setup com um token recém-copiado.

Avançado: substituindo os endpoints OIDC

Se o FPL alterar seu cliente ou endpoints OIDC, você pode substituir os padrões com variáveis de ambiente (todas opcionais):

VariávelPadrão
FPL_OIDC_CLIENT_ID1f243d70-a140-4035-8c41-341f5af5aa12
FPL_OIDC_AUTHORITYhttps://account.premierleague.com/as
FPL_TOKEN_URL<FPL_OIDC_AUTHORITY>/token

Limitações

  • A API do FPL não é oficialmente documentada e pode mudar sem aviso
  • Apenas operações de leitura são suportadas atualmente

Solução de Problemas

Problemas Comuns

1. Erro "spawn fpl-mcp ENOENT" no Claude Desktop

Isso ocorre porque o Claude Desktop não consegue encontrar o executável fpl-mcp no seu PATH.

Solução: Use uma destas abordagens:

  • Use o caminho completo para o executável no seu arquivo de configuração

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

  • Use Python para executar o módulo diretamente (método preferido)

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

2. O servidor desconecta imediatamente

Se o servidor iniciar mas desconectar imediatamente:

  • Verifique os logs em ~/Library/Logs/Claude/mcp*.log (macOS) ou %APPDATA%\Claude\logs\mcp*.log (Windows)
  • Certifique-se de que todas as dependências estão instaladas
  • Tente executar o servidor manualmente com python -m fpl_mcp para ver quaisquer erros

3. Servidor não aparecendo no Claude Desktop

Se o ícone de martelo não aparecer:

  • Reinicie o Claude Desktop completamente
  • Verifique se seu claude_desktop_config.json tem sintaxe JSON correta
  • Certifique-se de que o caminho para Python ou o executável é absoluto, não relativo

Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

  1. Faça um fork do repositório
  2. Crie sua branch de recurso (git checkout -b feature/amazing-feature)
  3. Faça commit das suas alterações (git commit -m 'Add some amazing feature')
  4. Envie para a branch (git push origin feature/amazing-feature)
  5. Abra um Pull Request

Para mais detalhes, consulte o arquivo CONTRIBUTING.md.

Agradecimentos

Citação

Se você usar este pacote em sua pesquisa ou projeto, considere citá-lo:

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