Brazilian Data MCP Gateway

This is a Model Context Protocol (MCP) implementation designed to expose various authoritative Brazilian public information repositories through a unified, protocol-compliant interface, leveraging the services aggregated by the Brasil API.

System Overview

The Brazilian Data MCP Gateway functions as an intermediary layer, translating standardized MCP requests into queries against specific Brazilian data sources. It standardizes the retrieval of complex national data elements, making them accessible and consumable by AI agents.

Key data domains supported include:

• Address Mapping (via CEP/Postal Codes)
• Legal Entity Validation (CNPJ)
• Interbank Transaction Codes and Details
• Telecommunication Area Codes (DDD)
• National Statistical Data (IBGE)
• Foreign Exchange Quotations (Cambio)
• National Internet Domain Status (.br)

Deployment Instructions

To set up the required execution environment:

bash

Obtain the source code repository

git clone https://github.com/guilhermelirio/brasil-api-mcp cd brasil-api-mcp

Install requisite software packages

npm install

Compile the source code

npm run build

Execution

Execute the compiled server component:

bash npm start

This action initializes the MCP endpoint, utilizing standard input/output (stdio) streams for communication with the calling system.

Accessible Functionality Modules

Postal Code Lookup (CEP)

• cep-search: Retrieve comprehensive address structure associated with a given Brazilian postal identifier.

Corporate Registry Lookup (CNPJ)

• cnpj-search: Obtain official registration details for a business entity using its unique CNPJ number.

Banking Sector Data

• bank-search: Look up specific details for a financial institution based on its identification code.
• bank-list: Generate a comprehensive roster of recognized Brazilian financial entities.

Telecommunication Area Codes (DDD)

• ddd-search: Query information pertaining to a specific geographic area code.

Geographic and Statistical Information (IBGE)

• ibge-states-list: Enumerate all federative units within Brazil, including metadata.
• ibge-state-search: Retrieve data for a particular state using its official code or acronym.
• ibge-municipalities-list: Fetch the complete listing of administrative subdivisions within a specified state.

Currency Exchange Benchmarks (Cambio)

• cambio-currencies-list: Present a catalog of all tradable currencies tracked for rates.
• cambio-rate: Fetch the official exchange valuation for a selected currency on a specified historical date.

Domain Registry Verification (Registro BR)

• registrobr-domain-check: Determine the availability and current registration status of a '.br' top-level domain.

Operational Examples

Retrieving Address Details via CEP

typescript // Example invocation for the postal code tool const result = await callMcpTool("cep-search", { cep: "01001000" });

// Expected output schema contains location components: // { cep: "01001000", state: "SP", city: "São Paulo", neighborhood: "Sé", street: "Praça da Sé", service: "viacep" }

Obtaining Historical Exchange Quotations

typescript // Example request for the exchange rate function (e.g., USD on a known date) const rateData = await callMcpTool("cambio-rate", { currency: "USD", date: "2023-08-10" });

// Detailed financial metrics are returned in the response payload.

Attributions

This utility leverages the aggregate data streams provided by the foundational Brasil API. Gratitude is extended to the maintainers of that core resource for making Brazilian public information accessible.

Software License

Distributed under the MIT License. © Guilherme Lirio Tomasi de Oliveira