Content
# 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
- **main.py** - AI chatbot using LangChain with Ollama for natural language queries
- **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
```
### Running the Chatbot (The chatbot it's just for test, make sure to setup the MCP server into a real AML Agentic AI enviroment to proper use)
The chatbot provides a natural language interface to query sanctions databases:
```bash
python main.py
```
**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
## Chatbot Demo
I'm testing with a local chatbot based in Ollama but the MCP as you know can be plugged to any Agentic AI:
- **LLM**: Ollama with qwen3:8b model
- **Agent**: LangChain create_agent with tool calling
- **Tools**: Custom LangChain tools wrapping the sanctions API
## Architecture
```
User Query (Natural Language)
↓
LangChain Agent (Ollama)
↓
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 |
| Ollama not running | Start Ollama service: `ollama serve` |
| Model not found | Pull model: `ollama pull qwen3:8b` |
| 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/
- **LangChain**: https://python.langchain.com/
- **Ollama**: https://ollama.ai/
**Last Updated**: June 2026
**API Base URL**: https://api.portaldatransparencia.gov.br/api-de-dados
