# Brazilian Sanctions MCP Server

An MCP (Model Context Protocol) server that provides access to Brazilian sanctions databases through the Porta da Transparência API.

## Components

- **mcp_server.py** - MCP server exposing Brazilian sanctions search tools
- **BrazillianSanctions.json** - MCP configuration file

## Features

- Search across 5 Brazilian sanctions registers
- Extract specific fields from API responses (names, sanctioning authorities, dates, locations)
- Check if sanctions are still active based on end dates
- Get comprehensive overview with maximum information from all registers
- A simple Natural language interface via AI chatbot (only for tests)
- Search by CNPJ, CPF, or company name
- Detailed sanction information including reasons, dates, and agencies
- Secure API key authentication
- Async-compatible tool execution

## Sanctions Registers Supported

| Register | Purpose | Search By |
|----------|---------|-----------|
| CNEP | National Register of Punishments | CNPJ, CPF |
| CEPIM | Register of Sanctioned Public Employees | CNPJ, CPF |
| CEIS | Register of Ineligible Entities | CNPJ, CPF |
| CEAF | Ineligibility Register of Public Servants | CPF |
| Leniency Agreements | Leniency Agreement Records | Name, CNPJ |

**Important**: Name search is only available for Leniency Agreements. The other registers (CNEP, CEIS, CEPIM, CEAF) only support CNPJ/CPF searches due to API limitations.

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

```bash
python mcp_server.py
```

OR

To use in Claude/Cursor use

```bash
\BrazillianSanctions.json
```

**Example queries:**
- "Need to know if 30.477.220/0001-71 is sanctioned by Brazil and if yes why?"
- "Search for Petrobras in leniency agreements"
- "Check if company with CNPJ 11222333000181 has any sanctions"

## MCP Server Tools

The MCP server exposes the following tools:

### Search Tools
- **search_cnep** - Search CNEP (National Register of Punishments) by CNPJ, CPF, agency, or date range
- **search_cepim** - Search CEPIM (Register of Sanctioned Public Employees) by CNPJ, CPF, or superior agency
- **search_ceis** - Search CEIS (Register of Ineligible Entities) by CNPJ, CPF, agency, or date range
- **search_ceaf** - Search CEAF (Ineligibility Register of Public Servants) by CPF, agency, or date range
- **search_acordos_leniencia** - Search Leniency Agreements by name, CNPJ, status, or date range
- **search_all_registers** - Search all registers for a given CNPJ or CPF

### Analysis Tools
- **check_sanction_status** - Check if an entity is still sanctioned across all registers based on end dates
- **get_sanctioning_authorities** - Get information about who sanctioned the entity (sanctioning agencies)
- **get_location_info** - Get location/state information (UF, agency location) for sanctioned entities
- **get_comprehensive_overview** - Get comprehensive overview with maximum information from all registers including names, authorities, dates, location, and status

### Utility Tools
- **get_sanction_details** - Get detailed information about a specific sanction register type
- **check_entity_sanctions** - Complete sanctions check for an entity across all registers
- **batch_search** - Search multiple documents (CNPJs or CPFs) in one operation
- **generate_sanctions_report** - Generate a formatted text report from multiple search results

## Architecture

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

## Document Formatting

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

```python
# These are equivalent:
"12.345.678/0001-00"
"123456780001000"
"123.456.789-66"
"12345678966"
```

## 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 CNPJ/CPF format and check if entity exists |

## 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/
- **Ollama**: https://ollama.ai/

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