Apuração Eleições 2026 (TSE) — servidor MCP + bot Telegram

Resultados oficiais e parciais das eleições brasileiras, direto dos arquivos públicos da divulgação do TSE (resultados.tse.jus.br), como tools MCP para Claude, Cursor, VS Code e qualquer cliente Model Context Protocol — e, opcionalmente, como bot inline do Telegram.

• 1º turno: domingo 04/10/2026 · 2º turno: 25/10/2026
• Sem chave, sem cadastro: o TSE publica os JSON abertamente. Este projeto só decifra os códigos (sp-c0003-e006259-u.json…), faz cache respeitoso (≥ 45 s por arquivo, If-Modified-Since) e normaliza a resposta. Em 2026 o TSE publica o agregado UF/BR no mesmo formato "completo" (dados/<uf>/<uf>-c<cargo>-e<eleicao>-u.json) do arquivo por município; o simplificado (dados-simplificados/…-r.json, 2022) saiu do portal — a v0.1.1 lê os dois e escolhe o que existe.
• Neutralidade: só números oficiais, sempre com apurado_pct e o horário do TSE. Nenhuma projeção, nenhum comentário, nenhum anúncio.
• Listado em awesome-mcp-brasil — hub curado e auto-verificado de servidores MCP e skills brasileiros (categoria Eleições / Governo).

Instalar

Docker (imagem publicada em ghcr.io)

docker run -i --rm ghcr.io/daniel-filius/apuracao-2026-mcp:v0.1.1

Claude Desktop (claude_desktop_config.json) / Cursor / VS Code (mcp.json):

{
  "mcpServers": {
    "apuracao-2026": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/daniel-filius/apuracao-2026-mcp:v0.1.1"]
    }
  }
}

Sem Docker (Python 3.11+ e uv)

uvx --from git+https://github.com/daniel-filius/apuracao-2026-mcp apuracao-mcp

{
  "mcpServers": {
    "apuracao-2026": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/daniel-filius/apuracao-2026-mcp", "apuracao-mcp"]
    }
  }
}

Claude Code:

claude mcp add apuracao-2026 -- uvx --from git+https://github.com/daniel-filius/apuracao-2026-mcp apuracao-mcp
# ou
claude mcp add apuracao-2026 -- docker run -i --rm ghcr.io/daniel-filius/apuracao-2026-mcp:v0.1.1

Também está no registro MCP oficial como io.github.daniel-filius/apuracao-2026.

Tools

Cargos: presidente, governador, senador, deputado_federal, deputado_estadual, deputado_distrital, prefeito, vereador.

Toda resposta inclui:

{
  "fonte": "TSE – divulgação oficial, resultado parcial",
  "atualizado_em": "04/10/2026 19:32:11",
  "apurado_pct": 87.31,
  "matematicamente_definido": false,
  "eleicao": {"ano": 2026, "turno": 1, "codigo": "…", "ciclo": "ele2026"},
  "cargo": "Governador", "abrangencia": "SP",
  "totais": {"votos_validos": 0, "brancos": 0, "nulos": 0, "abstencao_pct": 0.0, "…": "…"},
  "candidatos": [
    {"posicao": 1, "nome": "…", "numero": "10", "partido": "…", "votos": 0, "pct": 0.0, "situacao": "…", "eleito": false}
  ]
}

Exemplos de pergunta ao agente: "quem está na frente para governador do RS?", "como está a apuração para presidente?", "resultado de prefeito em Campinas em 2024".

Antes de o TSE publicar o pleito de 2026

Os códigos de 2026 só aparecem no config oficial (ele-c.json) perto da votação. Até lá, as tools explicam isso e você pode usar dados históricos: ano=2022 (Eleições Gerais, 1º/2º turno) e ano=2024 (municipais).

apuracao-mcp --smoke                 # lê o config do TSE e imprime o ciclo atual
apuracao-mcp --demo SP governador    # resultado normalizado (2022) sem iniciar o MCP

Bot Telegram (opcional)

@Apuracao2026Bot em qualquer grupo: @Apuracao2026Bot SP governador ou @Apuracao2026Bot br. Comandos: /start, /br, /uf SP [cargo].

O bot só sobe se existir APURACAO_BOT_TOKEN (ver .env.example); sem token ele sai imediatamente. Long polling, stdlib apenas, métricas anônimas (ids hasheados) em metrics.jsonl.

APURACAO_BOT_TOKEN=... apuracao-bot

Desenvolvimento

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest -q                       # fixtures reais do TSE (2022) em fixtures/
python -m apuracao_mcp.server   # stdio

Publicação: tag vX.Y.Z → workflow publish-mcp.yml roda os testes, publica a imagem em ghcr.io/daniel-filius/apuracao-2026-mcp e registra no registro MCP oficial via GitHub OIDC (server.json).

Apoie

Projeto voluntário, sem fins políticos e sem anúncios. Se foi útil na noite da apuração, um Pix ajuda a manter em 2028:

Pix copia-e-cola (valor livre):

00020101021226530014br.gov.bcb.pix0131danielfilho.workspace@gmail.com5204000053039865802BR5913DANIEL FILIUS6009SAO PAULO62160512APURACAO20266304CC54

Mudanças

• v0.1.1 (2026-10-05) — hotfix da noite do 1º turno: o TSE deixou de publicar o agregado UF/BR em dados-simplificados/…-r.json (404 NoSuchKey) e passou a servi-lo em dados/<uf>/<uf>-c<cargo>-e<eleicao>-u.json. resultado/resumo_brasil agora tentam o formato completo, caem para o simplificado (histórico 2022) e memorizam o que funcionou; fixtures reais de 2026 (SP governador, BR presidente, ele-c.json de 05/10) entraram nos testes.
• v0.1.0 (2026-09-28) — primeira publicação no registro MCP (OCI em ghcr.io).

Fonte e limites

• Dados: divulgação oficial do TSE (https://resultados.tse.jus.br/oficial/…). Este projeto não é vinculado ao TSE. Números "parciais" podem mudar até a totalização final.
• Cache: 45 s por arquivo de resultado, 5 min para o config, 1 h para a lista de municípios; sem varredura de todas as UFs a cada chamada.
• User-Agent identifica o projeto.

Licença MIT.