Brasil API

🚀 Brasil API MCP

A Model Context Protocol (MCP) server that provides tools to query various Brazilian public data services through Brasil API.

🚀 Quick Start

Brasil API MCP serves as a bridge between AI assistants and Brazilian public data services, achieved through the standardized Model Context Protocol. It offers access to the following types of information:

• Zip Code (CEP)
• Company Registration Number (CNPJ)
• Bank Information
• Area Code (DDD)
• IBGE (Brazilian Institute of Geography and Statistics) Data
• Foreign Exchange Rates
• Domain Registration Status (.br Domains)

📦 Installation

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

Basic Usage

Run the server:

npm start

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

✨ Features

Available Tools

CEP (Zip Code)

• cep-search - Query address information for Brazilian zip codes.

CNPJ (Company Registration Number)

• cnpj-search - Query information about Brazilian companies based on their CNPJ.

Banks

• bank-search - Find information about Brazilian banks based on their codes.
• bank-list - List all Brazilian banks.

DDD (Area Code)

• ddd-search - Query information about Brazilian area codes (DDD).

IBGE (Geography and Statistics Institute)

• ibge-states-list - List all Brazilian states and their information.
• ibge-state-search - Find information about Brazilian states based on their codes or abbreviations.
• ibge-municipalities-list - List all municipalities under a Brazilian state based on its abbreviation.

Foreign Exchange (Cambio)

• cambio-currencies-list - List all currencies for which foreign exchange rates can be queried.
• cambio-rate - Query the exchange rate information of a specific currency on a particular date.

Registro BR (Domain Registration)

• registrobr-domain-check - Check the status and availability of .br domains.

Advanced Usage

Query a Brazilian address by zip code

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

// The response provides detailed address information:
// {
//   cep: "01001000",
//   state: "SP",
//   city: "São Paulo",
//   neighborhood: "Sé",
//   street: "Praça da Sé",
//   service: "viacep"
// }

Get foreign exchange rate information

// Example request to get the US dollar exchange rate
const response = await callMcpTool("cambio-rate", {
  currency: "USD",
  date: "2023-08-10"
});

// The response provides detailed exchange rate information

📄 License

MIT © Guilherme Lirio Tomasi de Oliveira