brasil-api-mcp

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