College Football Data

Acesse estatísticas de futebol americano universitário da API College Football Data.

Documentação

Servidor MCP de Dados de Futebol Universitário

Um servidor MCP que fornece acesso a estatísticas de futebol universitário, com dados da College Football Data API V2 dentro do Claude Desktop.

Visão Geral

Este servidor Model Context Protocol (MCP) permite que assistentes de IA e aplicativos:

Consultem estatísticas e dados abrangentes de futebol universitário
Acessem resultados de jogos, registros de times e estatísticas de jogadores
Analisem dados de jogada a jogada e resumos de drives
Visualizem rankings e métricas de probabilidade de vitória
Comparem desempenhos de times e gerem insights

Os usuários podem executar consultas usando linguagem natural.

Exemplo de Saída

P. Qual foi a maior zebra entre os jogos da FCS durante a temporada de 2014?

R. Deixe-me ajudar a encontrar a maior zebra da FCS em 2014. Vou analisar os dados dos jogos, focando em partidas entre times da FCS onde havia uma diferença significativa na força dos times e um resultado inesperado.

Os dados sugerem que houve várias zebras notáveis na FCS durante 2014, mas uma que se destaca foi a vitória da Eastern Washington sobre Washington por 52-59 em 6 de setembro de 2014. Isso foi particularmente significativo porque:

Washington era um time da FBS da conferência Pac-12
O jogo foi disputado no estádio de Washington (Husky Stadium)
A probabilidade de vitória da Eastern Washington era de apenas 1,4% de acordo com as estatísticas pós-jogo
Os 59 pontos marcados pela Eastern Washington foram os maiores já feitos por um time da FCS contra um adversário da Pac-12
Washington era favorita por vários pontos antes do jogo

Outras zebras notáveis da FCS naquela temporada incluíram:

North Dakota State derrotando Iowa State por 34-14
Bethune-Cookman derrotando FIU por 14-12
Northern Iowa quase surpreendendo Iowa (perdeu por 31-23)

No entanto, Eastern Washington sobre Washington parece ser a maior zebra da temporada de 2014 da FCS, considerando:

A diferença de divisões (FCS vs FBS)
O nível do adversário da FBS (conferência Power 5)
A margem de pontos e o desempenho ofensivo do azarão
A importância histórica como uma das maiores vitórias da FCS sobre um time Power 5
O fato de ter acontecido fora de casa, em um ambiente hostil

Pré-requisitos

Python 3.11 ou superior
Gerenciador de pacotes UV (recomendado)
Uma chave da College Football Data API (obtenha uma aqui)

Instalação

Instalando via Smithery

Para instalar o College Football Data Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install cfbd --client claude

Clone este repositório:

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

Crie e ative um ambiente virtual:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Instale as dependências:

uv pip install -e .

Crie um arquivo .env na raiz do projeto e adicione sua chave de API:

CFB_API_KEY=your_api_key_here

Instalação Manual

Clone este repositório:

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

Crie e ative um ambiente virtual:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Instale as dependências:

uv pip install -e .

Crie um arquivo .env na raiz do projeto e adicione sua chave de API:

CFB_API_KEY=your_api_key_here

Uso

Executando o Servidor

Inicie o servidor:

uv run cfbd-mcp-server

Conectando com o Claude Desktop

Abra a configuração do Claude Desktop em:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Adicione a configuração do servidor:

{
    "mcpServers": {
        "cfbd-mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "/full/path/to/cfbd-mcp-server",
                "run",
                "cfbd-mcp-server"
            ],
            "env": {
                "CFB_API_KEY": "xxx",
                "PATH": "/full/path/to/python"
            }
        }
    }
}

Feche e reinicie o Claude Desktop

Após reiniciar, você pode confirmar a instalação clicando no sinal de mais no canto inferior esquerdo da caixa de texto. Se for bem-sucedido, você verá "Add from cfbd-mcp-server" como uma das opções do menu. Aqui está um exemplo de captura de tela.

Screenshot of successful install

Atualizando após a instalação

Baixe os arquivos atualizados

cd cfbd-mcp-server
git pull

Desinstale o pacote existente:

uv pip uninstall cfbd-mcp-server

Exclua artefatos de build e metadados existentes

Para Windows:

rmdir /s /q build dist
del /s /q *.egg-info

Para macOS:

rm -rf build dist *.egg-info

Instale o pacote revisado e suas dependências

uv pip install -e .
uv sync --dev --all-extras

uv run cfbd-mcp-server

Feche e reinicie o Claude Desktop

Recursos

Resources

Acesse a documentação de esquema para todos os endpoints:

schema://games - Informações de jogos e placares
schema://records - Registros de temporada dos times
schema://games/teams - Dados detalhados de jogos por time
schema://plays - Informações de jogada a jogada
schema://drives - Resumos e resultados de drives
schema://play/stats - Estatísticas individuais de jogadas
schema://rankings - Rankings de times em diferentes pesquisas
schema://metrics/wp/pregame - Probabilidades de vitória pré-jogo
schema://game/box/advanced - Estatísticas avançadas de box score

Tools

Consulte endpoints diretamente:

get-games - Recuperar dados de jogos
get-records - Obter registros de times
get-games-teams - Acessar estatísticas de jogos por time
get-plays - Consultar dados de jogada a jogada
get-drives - Analisar informações de drives
get-play-stats - Visualizar estatísticas de jogadas
get-rankings - Verificar rankings de times
get-pregame-win-probability - Ver probabilidades de vitória
get-advanced-box-score - Acessar estatísticas e análises detalhadas de jogos

Prompts

Modelos de análise pré-construídos:

analyze-game - Obter análise detalhada de um jogo específico
analyze-team - Análise abrangente de um único time
analyze-trends - Analisar tendências ao longo de uma temporada
compare-teams - Comparar o desempenho de dois times
analyze-rivalry - Analisar confrontos históricos de rivalidade

Limites da API

A College Football Data API é gratuita, mas possui limite de requisições:

Nível gratuito: Requisições limitadas por minuto
Assinantes do CFBD Patreon têm limites maiores
Use padrões de consulta eficientes para evitar atingir os limites
Lide com erros de limite de requisições de forma graciosa

Desenvolvimento

Estrutura do Projeto

cfbd-mcp-server/
├── README.md
├── pyproject.toml
└── src/
    └── cfbd_mcp_server/
        ├── .env
        ├── __init__.py
        ├── cfbd_schema.py
        ├── schema_helpers.py
        └── server.py

Configuração para Desenvolvimento

Clone o repositório
Instale as dependências de desenvolvimento:

uv pip install -e ".[dev]"

Execute os testes:

pytest

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça commit das suas alterações
Envie para o seu fork
Envie um pull request

Solução de Problemas

Problemas Comuns

Erros de Chave de API
- Verifique se sua chave de API está configurada corretamente nos arquivos .env e claude_desktop_config.json
- Confirme se a chave é válida em collegefootballdata.com
Limite de Requisições
- Espaçe as requisições quando possível
- Considere a assinatura do Patreon para limites maiores
- Implemente cache para dados acessados com frequência
Problemas de Conexão
- Verifique a conectividade com a internet
- Confira o status da API em collegefootballdata.com
- Garanta o tratamento adequado de erros no seu código

Obtendo Ajuda

Abra uma issue no GitHub
Revise a documentação da API
Acesse o Discord do College Football Data

Licença

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

Agradecimentos

College Football Data por fornecer a API
Model Context Protocol pela especificação do MCP