README.md•3 kB
# 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)