MCP 服务器

MCP DivulgaCandContas Server

Enables querying Brazilian electoral data through TSE's official API. Supports candidate searches, election information, and campaign finance records for municipalities and states.

README

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:

# Tornar o script executável (apenas uma vez)
chmod +x mcp-server.sh

# Ver todas as opções disponíveis
./mcp-server.sh help

# Construir o projeto
./mcp-server.sh build

# Executar localmente
./mcp-server.sh run

# Construir e executar com Docker
./mcp-server.sh build-docker
./mcp-server.sh run-docker

# Executar testes
./mcp-server.sh test

# Ver configuração para Claude Desktop
./mcp-server.sh config

# Limpar arquivos gerados
./mcp-server.sh clean

📦 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:

docker run -it --rm karnagge/mcp-divulgacandcontas:latest

Via Docker

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

# Baixar e executar diretamente do Docker Hub
docker run -it --rm karnagge/mcp-divulgacandcontas:latest

# Ou executar como daemon
docker run -d --name mcp-server -p 3000:3000 karnagge/mcp-divulgacandcontas:latest

Opção 2: Build local

Clone o repositório:

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

Build da imagem:

docker build -t mcp-divulgacandcontas .

Execute o container:

docker run -p 3000:3000 mcp-divulgacandcontas

Instalação Local

Instalar dependências:

npm install
# OU usando o script
./mcp-server.sh build

Compilar TypeScript:

npm run build

Executar servidor:

npm start
# OU usando o script
./mcp-server.sh run

Modo Desenvolvimento

npm run dev
# OU usando o script para desenvolvimento contínuo
npm run watch  # Em um terminal
./mcp-server.sh run  # Em outro terminal

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

{
  "mcpServers": {
    "divulgacandcontas": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "mcp-divulgacandcontas-server:latest"
      ]
    }
  }
}

Usando Node.js Local

{
  "mcpServers": {
    "divulgacandcontas": {
      "command": "node",
      "args": ["/caminho/absoluto/para/build/index.js"]
    }
  }
}

Usando NPX (se publicado)

{
  "mcpServers": {
    "divulgacandcontas": {
      "command": "npx",
      "args": ["-y", "mcp-divulgacandcontas-server"]
    }
  }
}

Uso das Ferramentas

Exemplo: Listar candidatos de São Paulo em 2020

// Parâmetros necessários
{
  "ano": 2020,
  "municipio": 35157,  // Código de São Paulo
  "eleicao": 2030402020,  // Eleições municipais 2020
  "cargo": 11  // Prefeito
}

Exemplo: Consultar informações de um candidato

{
  "ano": 2020,
  "municipio": 35157,
  "eleicao": 2030402020, 
  "candidato": 123456  // Código do candidato
}

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

{
  "ano": 2020,
  "uf": "SP"
}

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

mcp-divulgacandcontas-server/
├── src/
│   └── index.ts          # Servidor MCP principal
├── build/                # Código compilado (gerado)
├── Dockerfile           # Configuração Docker
├── docker-compose.yml   # Configuração Docker Compose
├── package.json         # Dependências e scripts
├── tsconfig.json        # Configuração TypeScript
└── README.md           # Esta documentação