BrasilAPI (CNPJ, CEP, validation, holidays)

io.github.renatocttiPublished by GitHub account renatocttiv0.1.0Updated Nov 11, 2026

Brazilian public data via BrasilAPI: CNPJ and partners, CEP, CNPJ/CPF validation, holidays

The publisher's own server: cnpj.ai

Overview

AI-generated overview

Gives assistants Brazilian public data via BrasilAPI: CNPJ company lookups with partners, CEP address lookup, offline CNPJ/CPF validation and national holidays.

What you can do
  • Look up a company by CNPJ: legal name, status, main activity, address, size, tax regime and partners
  • Validate CNPJ and CPF format and check digits locally, without network calls
  • Look up an address by CEP: street, neighborhood, city, state, IBGE code and coordinates
  • List national holidays for a year with their weekdays
When to use it
Useful for Brazilian company due-diligence and KYC checks, verifying that a supplier or customer exists and is active, cleaning address data from CEPs, or screening CNPJ/CPF numbers before trusting them.
Requirements
Runs locally over stdio via npx with Node 20 or newer; no account, API key or environment variable is needed. Network access to BrasilAPI is required for the CNPJ, CEP and holiday lookups; validation tools work offline.
Before you install
Lookups send the queried CNPJ or CEP to the third-party BrasilAPI service, which is a free community aggregator with rate limits and data that can lag the Receita Federal; treat results as a first check, not a certificate. Partner CPFs come masked and the server keeps no state between calls.

Installation

In SourceWeft

  1. Open BrasilAPI (CNPJ, CEP, validation, holidays) in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

brasilapi-mcp

An MCP server that gives AI assistants Brazilian public data through BrasilAPI: company registry lookups by CNPJ (including partners), addresses by CEP, offline CNPJ/CPF validation and national holidays.

It was built from experience with company due-diligence (KYC) workflows, where an agent has to check that a company exists, is active and who its partners are, and must not trust a number that fails its check digits. It is an independent project and is not affiliated with BrasilAPI or the Receita Federal.

Tools

ToolWhat it doesNetwork
lookup_cnpjLegal name, registration status, main activity, address, size, tax regime and partners (QSA) of a company. Accepts CNPJ with or without punctuation, numeric or alphanumeric.BrasilAPI
validate_cnpjChecks format and check digits, numeric and alphanumeric CNPJ.none
validate_cpfChecks format and check digits of a CPF. Nothing is stored or sent.none
lookup_cepStreet, neighborhood, city, state, IBGE code and coordinates for a CEP.BrasilAPI
list_holidaysNational holidays of a year, with weekdays.BrasilAPI

lookup_cnpj rejects a number with wrong check digits before making any request, so a typo costs nothing and never reaches the API. Partner CPFs come masked by the registry (***123456**); the server does not unmask or store anything.

Example, lookup_cnpj with include_partners: false:

json
{  "cnpj": "00000000000191",  "razaoSocial": "BANCO DO BRASIL SA",  "situacaoCadastral": { "descricao": "ATIVA", "desde": "2005-11-03", "motivo": "SEM MOTIVO" },  "tipo": "MATRIZ",  "naturezaJuridica": "Sociedade de Economia Mista",  "cnaePrincipal": { "codigo": 6422100, "descricao": "Bancos múltiplos, com carteira comercial" },  "endereco": { "municipio": "BRASILIA", "uf": "DF", "cep": "70040912", "...": "..." },  "totalSocios": 41}

Install

Requires Node 20 or newer.

Claude Code:

bash
claude mcp add brasilapi -- npx -y @renatoctti/brasilapi-mcp

Claude Desktop, Cursor and other clients that read an mcpServers block:

json
{  "mcpServers": {    "brasilapi": {      "command": "npx",      "args": ["-y", "@renatoctti/brasilapi-mcp"]    }  }}

From source:

bash
git clone https://github.com/renatoctti/brasilapi-mcpcd brasilapi-mcpnpm installnpm run buildnode dist/src/index.js   # speaks MCP over stdio

Notes

  • Data source. BrasilAPI is a free community service that aggregates public data. It has rate limits, and the server reports a 429 in plain words instead of retrying. Each request has a 10 second timeout.
  • Identification. BrasilAPI sits behind a firewall that refuses requests from anonymous default HTTP agents, so every request carries User-Agent: brasilapi-mcp/<version> (+repo url).
  • Alphanumeric CNPJ. Since 2026 the Receita Federal issues CNPJs with letters. The validator follows the published check-digit rule (the value of a character is its ASCII code minus 48). Whether a lookup finds the company depends on BrasilAPI having it.
  • Freshness. Registry data can be days behind the Receita Federal. Treat it as a first check, not as a certificate.
  • No state. The server keeps nothing between calls and writes no logs of the numbers you ask about; the only output on stderr is a start-up line.

Development

bash
npm test        # builds, then runs the unit and protocol tests (no network)npm run smoke   # starts the built server over stdio and calls every tool on the real API

The tests cover the check-digit rules (numeric and alphanumeric CNPJ, CPF), the reshaping of each answer, the error paths (not found, rate limit, unreachable) and the server itself through an in-memory MCP client, with a fake fetch standing in for BrasilAPI.

License

MIT

Source: README.md at commit bd7b861

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.0LatestNov 11, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Cnpj integrations