Brazilian PEP MCP Server

Brazilian PEP MCP 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