MCP DivulgaCandContas Server

Um servidor MCP (Model Context Protocol) que implementa todos os serviços da API DivulgaCandContas do TSE (Tribunal Superior Eleitoral), permitindo consultas sobre candidaturas e prestação de contas eleitorais.

Funcionalidades

Este servidor implementa as seguintes ferramentas (tools) baseadas na API oficial do TSE:

🏛️ Candidaturas

• listar_candidatos_municipio: Lista todos os candidatos em um município específico

• consultar_candidato: Consulta informações detalhadas de um candidato

🗳️ Eleições

• listar_anos_eleitorais: Lista anos eleitorais disponíveis

• listar_eleicoes_ordinarias: Lista eleições ordinárias disponíveis

• listar_eleicoes_suplementares: Lista eleições suplementares por estado/ano

• listar_cargos_municipio: Lista cargos em disputa em um município

💰 Prestação de Contas

• consultar_prestador_contas: Consulta informações de prestação de contas de candidatos

Instalação e Uso

Script de Gerenciamento (Recomendado)

Este projeto inclui um script de gerenciamento que facilita todas as operações:

📦 Imagem Docker

A imagem Docker está disponível no Docker Hub:

🔗 Docker Hub: karnagge/mcp-divulgacandcontas

📋 Tags disponíveis:

• latest - Versão mais recente

• v1.0.0 - Versão estável 1.0.0

💾 Tamanho: ~227MB (otimizada com Alpine Linux)

🔧 Uso rápido:

Via Docker

Opção 1: Usar imagem pré-construída (Recomendado)

Opção 2: Build local

1. Clone o repositório:

   git clone https://github.com/karnagge/mcpcand.git cd mcpcand

2. Build da imagem:

   docker build -t mcp-divulgacandcontas .

3. Execute o container:

   docker run -p 3000:3000 mcp-divulgacandcontas

Instalação Local

1. Instalar dependências:

2. Compilar TypeScript:

3. Executar servidor:

Modo Desenvolvimento

Configuração com Claude Desktop

Para usar este servidor com Claude Desktop, adicione a seguinte configuração ao seu claude_desktop_config.json:

Usando Docker

Usando Node.js Local

Usando NPX (se publicado)

Uso das Ferramentas

Exemplo: Listar candidatos de São Paulo em 2020

Exemplo: Consultar informações de um candidato

Exemplo: Listar eleições suplementares em São Paulo

API Base

Este servidor consulta a API oficial do TSE:

• Base URL: https://divulgacandcontas.tse.jus.br/divulga/rest/v1

• Documentação: Swagger da API

Estrutura do Projeto

Desenvolvimento

Scripts Disponíveis

• npm run build - Compila TypeScript

• npm run start - Executa servidor compilado

• npm run dev - Compila e executa em modo desenvolvimento

• npm run watch - Monitora mudanças e recompila automaticamente

• npm run clean - Remove arquivos compilados

Dependências Principais

• @modelcontextprotocol/sdk: SDK oficial do MCP

• zod: Validação de schemas

• axios: Cliente HTTP para chamadas à API do TSE

Segurança e Limitações

• ✅ Dados públicos oficiais do TSE

• ✅ Timeout configurado (30s) para requisições

• ✅ Validação rigorosa de parâmetros com Zod

• ✅ Tratamento de erros da API

• ⚠️ Sujeito a limitações de rate limit da API do TSE

• ⚠️ Dados disponíveis conforme cronograma do TSE

Códigos Úteis

Códigos de Eleição Comuns

• 2030402020: Eleições Municipais 2020

• 2030402024: Eleições Municipais 2024

• 2030602022: Eleições Gerais 2022

Códigos de Cargo Comuns

• 11: Prefeito

• 13: Vice-prefeito

• 51: Vereador

• 1: Presidente

• 3: Governador

• 5: Senador

• 6: Deputado Federal

• 7: Deputado Estadual

Estados (UF)

Use a sigla de 2 letras: SP, RJ, MG, RS, etc.

Suporte

Este servidor implementa todos os endpoints documentados na API DivulgaCandContas do TSE. Para problemas ou dúvidas:

1. Verifique se os parâmetros estão corretos (ano, códigos de município, etc.)

2. Consulte a documentação oficial da API do TSE

3. Verifique se o serviço do TSE está disponível

Licença

MIT License - veja o arquivo LICENSE para detalhes.

Nota: Este é um projeto independente que utiliza a API pública do TSE. Não possui afiliação oficial com o Tribunal Superior Eleitoral.