Cartola FC MCP

Um servidor MCP que conecta o Cartola FC ao Claude (e outros agentes de IA). Com ele você pode perguntar ao Claude coisas como:

• "Quais jogos têm nesta rodada?"

• "Quem foram os 10 melhores jogadores da rodada?"

• "Me monta um time com C$ 120 no orçamento?"

• "Qual o status do Gabigol no mercado?"

O que você precisa ter instalado

Antes de começar, instale:

1. Python 3.11 ou mais novo

   • Baixe em: https://www.python.org/downloads/

   • Para verificar se já tem: abra o terminal e digite python3 --version

   • Se você usa Mac com Homebrew, também pode instalar via brew install python@3.13

2. Claude Desktop (para usar o MCP com o Claude)

   • Baixe em: https://claude.ai/download

Related MCP server: MLB SportRadar MCP Server

Instalação

1. Abra o terminal na pasta do projeto

Se você recebeu o projeto como arquivo ZIP, extraia e abra o terminal dentro da pasta cartola_mcp.

No Mac: clique com o botão direito na pasta → "Abrir Terminal aqui"

2. Instale as dependências

./mcp install

Esse comando cria um ambiente virtual isolado e instala tudo automaticamente. Você só precisa rodar uma vez.

3. Teste se o servidor funciona

./mcp rdev

Se tudo estiver certo, você verá algo como:

Starting MCP inspector...
MCP server running at stdio

Pressione Ctrl+C para parar.

Configurando no Claude Desktop

Para que o Claude Desktop use este MCP, você precisa informar onde o servidor está.

1. Encontre o arquivo de configuração do Claude Desktop

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

No Mac, abra o Finder, pressione Cmd+Shift+G e cole o caminho acima.

2. Edite o arquivo de configuração

Abra o arquivo claude_desktop_config.json em um editor de texto (pode ser o Bloco de Notas ou TextEdit).

Se o arquivo estiver vazio ou não existir, crie com o conteúdo abaixo. Se já tiver conteúdo, adicione apenas o bloco "cartola" dentro de "mcpServers".

{
  "mcpServers": {
    "cartola": {
      "command": "/CAMINHO/COMPLETO/PARA/cartola_mcp/.venv/bin/python",
      "args": [
        "/CAMINHO/COMPLETO/PARA/cartola_mcp/server.py"
      ]
    }
  }
}

Importante: Substitua /CAMINHO/COMPLETO/PARA/cartola_mcp pelo caminho real da pasta no seu computador (em dois lugares).

Para descobrir o caminho no Mac:

1. Abra o terminal na pasta cartola_mcp

2. Digite pwd e pressione Enter

3. Copie o resultado

Exemplo: se pwd retornou /Users/joao/projetos/cartola_mcp, a configuração ficará assim:

{
  "mcpServers": {
    "cartola": {
      "command": "/Users/joao/projetos/cartola_mcp/.venv/bin/python",
      "args": [
        "/Users/joao/projetos/cartola_mcp/server.py"
      ]
    }
  }
}

3. Reinicie o Claude Desktop

Feche completamente o Claude Desktop e abra de novo. O ícone de ferramenta deve aparecer na interface, indicando que o MCP está ativo.

Usando com o Claude

Depois de configurado, abra uma conversa no Claude Desktop e pergunte diretamente:

Ferramentas disponíveis

Problemas comuns

O Claude não está vendo as ferramentas do Cartola

• Verifique se o caminho no claude_desktop_config.json está correto

• Reinicie o Claude Desktop completamente (feche pelo ícone na barra de tarefas)

Erro "mercado fechado"

• O mercado do Cartola só fica aberto entre as rodadas. Durante os jogos ele fecha. Tente novamente depois que a rodada terminar.

Erro ao buscar time

• O slug do time fica na URL do Cartola FC quando você acessa o seu time. Exemplo: cartola.globo.com/time/meu-time-123 → slug é meu-time-123

Erro de instalação

• Certifique-se de ter o Python 3.11+ instalado: python3 --version

• Tente reinstalar o uv e repetir o passo de instalação

Testando sem o Claude Desktop

Se quiser testar as ferramentas diretamente (sem o Claude), use o MCP Inspector:

./mcp rdev

Isso abre uma interface web onde você pode chamar cada ferramenta manualmente e ver as respostas.

Estrutura do projeto

cartola_mcp/
├── server.py          # Ponto de entrada do servidor MCP
├── client.py          # Configuração das chamadas à API do Cartola
├── tools/
│   ├── rodadas.py     # Rodadas e partidas
│   ├── atletas.py     # Mercado e pontuações
│   └── times.py       # Times dos cartoleiros
├── resources/
│   └── clubes.py      # Dados dos clubes do Brasileirão
├── .env               # Configurações (URL e timeout da API)
└── requirements.txt   # Dependências Python