apuracao-2026
This server exposes official TSE Brazilian election results (2026 live, plus 2022/2024 history) as MCP tools for Claude, Cursor, VS Code and other MCP clients — no key or signup needed.
listar_eleicoes()— lists the ordinary elections in the official TSE config (cycle, code, date, round, offices by scope) plus available history; use it first if you don't know which race is live.resultado(uf, cargo, turno=1, ano=None, limite=20)— official partial count for one office in a state (SP,RJ…) orBRfor president.resumo_brasil(turno=1, ano=None)— national presidential partial total.municipio(uf, municipio, cargo, turno=1, ano=None)— partial count per city, by exact name, IBGE code or TSE code (e.g.municipio('SP', 'São Paulo', 'governador')).Offices covered: presidente, governador, senador, deputado federal/estadual/distrital, prefeito, vereador; rounds 1 or 2.
Answers come normalized with source, TSE timestamp,
apurado_pct, totals (valid/blank/null/abstention) and a ranked candidate list with votes, percentage, status and elected flag.Historical data via
ano=2022(general) andano=2024(municipal), useful before the 2026 codes appear in the TSE config.Sample questions: "quem está na frente para governador do RS?", "como está a apuração para presidente?", "resultado de prefeito em Campinas em 2024".
Strictly neutral: only official numbers, no projections or commentary; respectful caching (45 s per file,
If-Modified-Since).Optional companion Telegram bot (
@Apuracao2026Bot) for inline queries like@Apuracao2026Bot SP governador— separate from the MCP server.
Provides an optional inline Telegram bot for querying official TSE election results, with commands such as /start, /br, and /uf SP [cargo].
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@apuracao-2026 como está a apuração para presidente?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 04/10/2026 (totalizado, validado ao vivo) · 2º turno: domingo 25/10/2026 — use
turno=2Sem 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_pcte 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.1Claude 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.1Também está no registro MCP oficial
como io.github.daniel-filius/apuracao-2026.
Related MCP server: onpe-mcp
Tools
Tool | O que devolve |
| Eleições ordinárias no config oficial do TSE (ciclo, código, data, turno, cargos por abrangência) e histórico disponível |
| Parcial oficial por UF ( |
| Presidente, total nacional |
| Parcial oficial por município (nome exato, código IBGE ou código TSE) |
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".
1º turno (04/10/2026) — validado ao vivo
Na noite da apuração o servidor (imagem v0.1.1) leu os arquivos reais do TSE. Resposta real de
resultado("SP", "governador"), resumida:
{
"fonte": "TSE – divulgação oficial, resultado parcial",
"atualizado_em": "05/10/2026 11:44:29",
"eleicao": {"ano": 2026, "turno": 1, "codigo": "6259", "ciclo": "ele2026", "nome": "Eleição Ordinária Estadual - 2026 1º Turno"},
"cargo": "Governador", "abrangencia": "SP",
"url_tse": "https://resultados.tse.jus.br/oficial/ele2026/6259/dados/sp/sp-c0003-e006259-u.json",
"apurado_pct": 100.0, "secoes_totalizadas": 103656, "secoes_total": 103656,
"totais": {"eleitorado": 34081699, "comparecimento_pct": 77.44, "votos_validos": 23130513, "brancos_pct": 5.11, "nulos_pct": 7.26},
"candidatos": [
{"posicao": 1, "nome": "TARCÍSIO", "numero": "10", "partido": "REPUBLICANOS", "votos": 14491874, "pct": 62.65, "situacao": "Eleito", "eleito": true},
{"posicao": 2, "nome": "FERNANDO HADDAD", "numero": "13", "partido": "PT", "votos": 8423656, "pct": 36.42, "situacao": "Não eleito", "eleito": false}
]
}2º turno — domingo 25/10/2026
Presidente (BR) e governador nas UFs em que ninguém passou de 50 % dos votos válidos. Basta
turno=2:
"como está a apuração do 2º turno para presidente?" →
resumo_brasil(turno=2)"2º turno para governador do RJ" →
resultado("RJ", "governador", turno=2)
O TSE inclui o 2º turno no config oficial (ele-c.json; eleições 6258 federal e 6260
estadual) pouco antes da votação. Até lá turno=2 devolve uma mensagem explicando isso (não um
erro genérico); no domingo 25/10 os resultados começam a aparecer a partir das 17h (Brasília), com
apurado_pct subindo até a totalização. O 1º turno continua disponível com turno=1.
Histórico: ano=2022 (Eleições Gerais, 1º/2º turno) e ano=2024 (municipais).
apuracao-mcp --smoke # lê o config do TSE e imprime o ciclo/eleições atuais
apuracao-mcp --demo SP governador # resultado normalizado sem iniciar o MCPBot 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-botDesenvolvimento
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 # stdioPublicaçã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 PAULO62160512APURACAO20266304CC54Mudanç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(404NoSuchKey) e passou a servi-lo emdados/<uf>/<uf>-c<cargo>-e<eleicao>-u.json.resultado/resumo_brasilagora 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.jsonde 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.
Available Tools
4 toolslistar_eleicoesListar eleiçõesA
Lista as eleições ordinárias presentes no config oficial do TSE (ciclo, código, data, turno e cargos por abrangência) e o histórico disponível. Use antes de resultado se não souber qual pleito está no ar.
Inputs: no named parameters. Returns: object
municipioResultado por municípioC
Resultado parcial oficial de um cargo em um município. municipio: nome exato, código IBGE (7 dígitos) ou código TSE. Ex.: municipio('SP', 'São Paulo', 'governador').
Inputs: uf (required), cargo (required), municipio (required), ano, +2 more. Returns: object
resultadoResultado por UFB
Resultado parcial oficial de um cargo em uma UF (ou BR para presidente). cargo: presidente, governador, senador, deputado_federal, deputado_estadual, deputado_distrital, prefeito, vereador. turno 1 ou 2. ano opcional (padrão: eleição ordinária mais próxima de hoje; 2022 para histórico).
Inputs: uf (required), cargo (required), ano, turno, +1 more. Returns: object
resumo_brasilResumo Brasil (presidente)B
Resultado parcial oficial para presidente, total nacional. turno 1 ou 2; ano opcional.
Inputs: ano, turno, limite. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Tools are mostly distinct by geographic scope: listar_eleicoes (election metadata), resultado (state-level results), resumo_brasil (national presidential summary), municipio (municipal results). However, resumo_brasil overlaps with resultado when cargo=presidente and UF=BR, which could cause confusion.
One tool follows a verb_noun pattern (listar_eleicoes), while the others are nouns (resultado, resumo_brasil, municipio). The mix is readable but not a consistent convention.
Four tools are well-scoped for a focused election results server: one for metadata, three for results at different geographic levels. Each tool earns its place without redundancy.
The surface covers listing elections, state-level results, national presidential summaries, and municipal results, with support for cargo, turno, and year. Minor gaps exist, such as candidate- or party-level drilldowns, but core retrieval workflows are covered.
Maintenance
Related MCP Connectors
Brazil 2026 election results (TSE): votes by candidate and city, parties, offices, assets.
Brazil 2026 election data from the TSE: ballot box reports, logs, results, SHA-256 and source link.
Brazilian election and legislative data (MCP Político, MCP Legislativo) for Claude and ChatGPT.
Query Brazil's public procurement portal (PNCP): tenders, contracts and price records.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables querying Brazilian electoral data through TSE's official API. Supports candidate searches, election information, and campaign finance records for municipalities and states.72MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for querying Peruvian electoral data (ONPE) including mesa results, candidate votes, and regional statistics. Enables natural language queries about the 2026 presidential election with local SQLite cache and live API fallback.-
- AlicenseNot gradedqualityDmaintenanceEnables querying and retrieving Brazilian electoral clearance certificates (Certidão de Quitação Eleitoral) from the TSE using CPF, name, voter ID, birth date, and filiation. It provides a single read-only tool via MCP for integration with AI assistants.MIT
- AlicenseNot gradedqualityDmaintenanceEnables querying Brazilian voter registration (título eleitoral) information from the official TSE source through a single read-only MCP tool.MIT