What is Brasil Api Mcp

brasil-api-mcp is a Model Context Protocol (MCP) server that connects AI assistants to various Brazilian public data services through the Brasil API, enabling access to a wide range of Brazilian data.

Use cases

Use cases include retrieving address information by postal code, checking company details via CNPJ, obtaining bank information, listing Brazilian states and municipalities, and checking currency exchange rates.

How to use

To use brasil-api-mcp, clone the repository from GitHub, install the dependencies using npm, and run the server with ‘npm start’. This will initiate the MCP server for communication via standard input/output.

Key features

Key features include querying postal codes (CEP), company registration (CNPJ), bank information, area codes (DDD), IBGE data, currency exchange rates, and domain registration status for .br domains.

Where to use

brasil-api-mcp can be used in applications requiring access to Brazilian public data, such as financial services, logistics, e-commerce, and any AI-driven solutions that need reliable Brazilian data.

Brasil API MCP

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

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

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

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

// 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

// 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 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