# Brasil API MCP

A Model Context Protocol (MCP) server that provides tools to query various Brazilian data services via the [Brasil API](https://brasilapi.com.br/).

## Overview

Brasil API MCP is a bridge that connects AI assistants to Brazilian public data services through the standardized Model Context Protocol. It provides access to various information such as:

- Postal Codes (CEP)
- Company Registration (CNPJ)
- Bank information
- Area codes (DDD)
- IBGE (Brazilian Institute of Geography and Statistics) data
- Currency exchange rates
- Domain registration status (.br domains)

## Installation

```bash
# Clone the repository
git clone https://github.com/guilhermelirio/brasil-api-mcp
cd brasil-api-mcp

# Install dependencies
npm install

# Build the project
npm run build
```

## Usage

To run the server:

```bash
npm start
```

This will start the MCP server that communicates via standard input/output (stdio).

## Available Tools

### CEP (Postal Codes)

- `cep-search` - Query address information from a Brazilian postal code (CEP)

### CNPJ (Company Registration)

- `cnpj-search` - Query information about a Brazilian company by its CNPJ (National Registry of Legal Entities)

### Banks

- `bank-search` - Find information about a Brazilian bank by its code
- `bank-list` - List all Brazilian banks

### DDD (Area Codes)

- `ddd-search` - Find information about a Brazilian area code (DDD)

### IBGE (Geography and Statistics)

- `ibge-states-list` - List all Brazilian states with their information
- `ibge-state-search` - Find information about a Brazilian state by its code or abbreviation
- `ibge-municipalities-list` - List all municipalities of a Brazilian state by its abbreviation

### Cambio (Currency Exchange)

- `cambio-currencies-list` - List all available currencies for exchange rates
- `cambio-rate` - Get exchange rates for a specific currency on a specific date

### Registro BR (Domain Registration)

- `registrobr-domain-check` - Check the status and availability of a .br domain name

## Integration Examples

### Querying a Brazilian Address by Postal Code

```typescript
// Sample request to the CEP tool
const response = await callMcpTool("cep-search", {
  cep: "01001000"
});

// Response provides address details:
// {
//   cep: "01001000",
//   state: "SP",
//   city: "São Paulo",
//   neighborhood: "Sé",
//   street: "Praça da Sé",
//   service: "viacep"
// }
```

### Getting Currency Exchange Rates

```typescript
// Sample request to get USD exchange rate
const response = await callMcpTool("cambio-rate", {
  currency: "USD",
  date: "2023-08-10"
});

// Response provides detailed exchange information
```

## Credits

This project uses the [Brasil API](https://brasilapi.com.br/) service, which aggregates various APIs related to Brazilian public data. Special thanks to the Brasil API team for providing this valuable service to the community.

## License

MIT © [Guilherme Lirio Tomasi de Oliveira](https://github.com/guilhermelirio)