Brazilian PEP Server

An MCP (Model Context Protocol) server that provides access to Brazilian PEP (Politically Exposed Persons) and federal public servants data through the Porta da Transparência API.

Components

• mcp_server.py - MCP server exposing Brazilian PEP and servants search tools
• pyproject.toml - Project dependencies and configuration
• requirements.txt - Python dependencies

Features

• Search PEPs (Politically Exposed Persons) by CPF, name, function, agency, or date ranges
• Search federal executive branch servers (civil and military)
• Query server remuneration data
• Search servers aggregated by agency
• Query functions and positions of trust
• Get comprehensive PEP status for individuals
• Extract specific fields from API responses
• Secure API key authentication
• Async-compatible tool execution

Data Sources

Source	Purpose	Search By
PEPs	Politically Exposed Persons	CPF, Name, Function, Agency, Date Ranges
Servidores	Federal Executive Branch Servers	CPF, Name, Agency, Type, Situation
Remuneração	Server Remuneration	CPF, ID, Month/Year
Por Órgão	Servers by Agency	Agency Code, Type, Link Type
Funções e Cargos	Functions and Positions	Pagination

API Key Configuration

An API key is REQUIRED to use this system.

Get your API key:

1. Visit: https://www.portaldatransparencia.gov.br/ (Brazilian CPF is required)
2. Login or create an account
3. Go to "Minha Conta" → "API Keys" or "Desenvolvedor"
4. Generate a new API key
5. Copy the key (format: abcd1234efgh5678ijkl9012)

Setup:

Create .env file in project root:

PORTAL_TRANSPARENCIA_API_KEY=your_key_here

SECURITY: Never commit your API key to version control!

Usage

Running the MCP Server

The MCP server can be run standalone or used by MCP clients:

python mcp_server.py

Example queries:

• "Check if CPF 123.456.789-00 is a PEP"
• "Search for servers named Silva in the Ministry of Economy"
• "Get remuneration data for server with CPF 987.654.321-00 for January 2026"
• "List all PEPs in agency 25000"
• "Search for functions and positions of trust"

MCP Server Tools

The MCP server exposes the following tools:

PEP Search Tools

• search_peps - Search PEPs by CPF, name, function, agency, or date ranges
• get_pep_info - Get comprehensive PEP information for a person by CPF

Servidor Search Tools

• search_servidores - Search federal executive branch servers by CPF, name, agency, type, or situation
• get_servidor_by_id - Get specific server by ID
• search_servidores_remuneracao - Search server remuneration by CPF or ID and month/year
• search_servidores_por_orgao - Search servers aggregated by agency
• search_funcoes_e_cargos - Search functions and positions of trust

Architecture

User Query (Natural Language)
    ↓
Tool Selection & Execution
    ↓
MCP Tools / Direct API Calls
    ↓
Brazilian PEP API
    ↓
Detailed PEP/Servant Information
    ↓
Natural Language Response

Document Formatting

The system automatically cleans document numbers (Brazilian CPF). Both formatted and unformatted documents work:

# These are equivalent:
"123.456.789-00"
"12345678900"

Error Handling

The system includes comprehensive error handling:

• API connection errors
• Invalid document formats
• Missing API keys
• Rate limiting
• Malformed responses

Troubleshooting

Issue	Solution
API key not found	Set PORTAL_TRANSPARENCIA_API_KEY in .env file
Connection timeout	Check internet connection and API status
No records found	Verify CPF format and check if person exists
401 Unauthorized	Verify API key is correct and active

References

• API Documentation: https://api.portaldatransparencia.gov.br/swagger-ui/index.html
• Porta da Transparência: https://www.portaldatransparencia.gov.br/
• MCP Protocol: https://modelcontextprotocol.io/

Last Updated: June 2026 API Base URL: https://api.portaldatransparencia.gov.br/api-de-dados