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.