home / mcp / mcp divulgacandcontas server

MCP DivulgaCandContas Server

Provides MCP access to DivulgaCandContas data for candidacies, elections, and campaign accounting from the TSE.

Installation

Add the following to your MCP client configuration file.

Configuration

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

You run an MCP (Model Context Protocol) server that exposes the DivulgaCandContas API from the TSE. It lets you query candidates, elections data, and campaign accounting information in a standardized MCP interface, so you can build reliable tools and dashboards on top of official public data.

How to use

You connect to the MCP server from your MCP client and invoke the available tools to fetch data such as candidates in a municipality, election years, and filing of accounts. You will not interact with raw HTTP endpoints directly; instead you call high-level MCP commands that the server exposes through its tools.

How to install

Prerequisites: you need Node.js and npm installed on your system. You may also run the server via Docker if you prefer containerized operation.

Step 1: Install dependencies or prepare the build script.

Step 2: Build the TypeScript sources.

Step 3: Run the MCP server locally or via management script.

Step 4: (Optional) Run the server inside Docker for isolation.

You can reuse the following practical commands to perform common tasks.

# Make the management script executable (once)
chmod +x mcp-server.sh

# See all available options
./mcp-server.sh help

# Build the project
./mcp-server.sh build

# Run the server locally
./mcp-server.sh run

# Build and run with Docker
./mcp-server.sh build-docker
./mcp-server.sh run-docker

# Run tests
./mcp-server.sh test

# Show Claude Desktop configuration
./mcp-server.sh config

# Clean generated files
./mcp-server.sh clean

Configuration and usage notes

This server connects to the official DivulgaCandContas API for data. You can use Docker, Node locally, or NPX to start an MCP instance. The Docker image is available with a lightweight Alpine base, and typical workflows include running in a container, building locally, or starting directly from a Node build.

Examples of common workflows

List candidates for a municipality in a given year, or fetch detailed information for a candidate. You can also retrieve available election years, regular and supplementary elections, and municipal cargos. Account-related data for candidates can be queried as well.

Notes on API base and endpoints

The server uses the official API base to fetch data from the TSE. It focuses on providing a stable MCP surface rather than exposing raw REST endpoints directly to clients.

Available tools

listar_candidatos_municipio

Lists all candidates in a specified municipality, enabling quick access to local candidate pools.

consultar_candidato

Fetches detailed information about a particular candidate, including biographical and electoral data.

listar_anos_eleitorais

Returns the available election years for planning and data retrieval.

listar_eleicoes_ordinarias

Provides a list of standard (regular) elections that occurred or will occur.

listar_eleicoes_suplementares

Lists supplementary elections by state and year for unmatched or re-run elections.

listar_cargos_municipio

Returns the cargos contested within a specific municipality.

consultar_prestador_contas

Queries campaign finance records and accounts information for candidates.