Cartola

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 [email protected]

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

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

---

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:

Pergunta	O que o Claude fará
"Em que rodada estamos?"	Consulta o status atual do Cartola
"Quais jogos têm esta rodada?"	Lista todas as partidas com horário e placar
"Quem foram os melhores desta rodada?"	Retorna o top 10 de pontuadores
"Quais atacantes estão disponíveis até C$ 15?"	Filtra o mercado por posição e preço
"Busca informações sobre o Endrick"	Detalha preço, média e status do atleta
"Monta um time com C$ 100 em 4-4-2"	Sugestão de escalação dentro do orçamento

---

Ferramentas disponíveis

Ferramenta	O que faz
rodada_atual	Status e número da rodada em andamento
listar_rodadas	Todas as rodadas do campeonato
listar_partidas	Partidas de uma rodada (com placar se já aconteceu)
atletas_pontuados	Todos os atletas com pontuação na rodada atual
top_pontuadores	Ranking dos melhores da rodada (filtrável por posição)
listar_mercado	Atletas disponíveis (filtrável por posição, status e preço)
buscar_atleta	Busca detalhada de um atleta pelo nome
buscar_time	Escalação e pontuação de um time do Cartola

---

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