# alanpcf/brasil-data-mcp [Health: Active]

**Category:** 📊 Data Platforms  
**Repository:** https://github.com/alanpcf/brasil-data-mcp  
**GitHub Stars:** 6  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/alanpcf-brasil-data-mcp

## Description
Brazilian public data for AI agents — companies (CNPJ), addresses (CEP), banks (BACEN), national holidays — via BrasilAPI. No auth, no API key. Install: npx -y brasil-data-mcp.

## Tools
Capabilities this server exposes over MCP:

- **consultar_cnpj** — Consulta dados cadastrais de uma empresa brasileira pelo CNPJ na Receita Federal (via BrasilAPI).  Retorna em JSON: razão social, nome fantasia, situação cadastral (ativa/baixada/etc), data de abertura,  endereço completo, CNAE principal e secundários, sócios (QSA), capital social, natureza jurídica,  porte (MEI/ME/EPP/Demais), telefones, e-mail, simples nacional/MEI.  Use quando o usuário pedir informações sobre uma empresa identificada por CNPJ.  NÃO use para: CPF (pessoa física), empresas estrangeiras, ou validação local de formato  (rejeite formato inválido sem chamar a tool). Aceita CNPJ com ou sem máscara.
- **consultar_cep** — Consulta endereço completo a partir de um CEP brasileiro via BrasilAPI v2 (agrega ViaCEP, Postmon e outros provedores com fallback automático).  Retorna em JSON: estado (UF), cidade, bairro, logradouro e, quando disponível, coordenadas geográficas.  Use quando o usuário pedir o endereço de um CEP, validar um CEP, ou descobrir cidade/UF a partir de um CEP.  NÃO use para: códigos postais de outros países, descobrir CEP a partir de endereço (a operação é só CEP → endereço, não inversa). Aceita CEP com ou sem hífen.
- **consultar_banco** — Consulta os dados de um banco brasileiro pelo código COMPE/Febraban via BrasilAPI (fonte: BACEN).  Retorna em JSON: nome curto, nome completo, código, ISPB (identificador no SPB).  Use quando o usuário fornecer um código de banco e quiser saber o nome, ou quando precisar do ISPB pra montar um PIX/TED.  NÃO use para: buscar banco por nome (use listar_bancos e filtre), validar conta corrente, ou consultar agência/conta. Códigos comuns: 001=BB, 104=CEF, 237=Bradesco, 341=Itaú, 260=Nubank, 077=Inter.
- **listar_bancos** — Lista TODOS os bancos brasileiros cadastrados no BACEN via BrasilAPI.  Retorna em JSON um array com nome, código COMPE/Febraban e ISPB de cada instituição.  Use quando o usuário quiser uma lista completa, buscar banco por nome (você filtra o resultado), ou descobrir o código de um banco específico cujo nome ele forneceu.  NÃO use quando o usuário já forneceu o código numérico — nesse caso use consultar_banco que é mais barato. A lista tem ~250 entradas; cite só os relevantes na resposta.
- **consultar_feriados** — Lista os feriados NACIONAIS brasileiros de um ano específico via BrasilAPI.  Retorna em JSON um array com data (YYYY-MM-DD), nome do feriado e tipo (national/optional). Inclui feriados móveis calculados (Carnaval, Páscoa, Corpus Christi).  Use quando o usuário perguntar quando cai um feriado, listar feriados do ano, planejar emendas/pontes, ou calcular dias úteis.  NÃO use para: feriados estaduais ou municipais (a API só cobre nacionais), datas comemorativas sem dia de folga (Dia das Mães etc.), ou anos fora da faixa 1900-2199.
- **consultar_ddd** — Lista as cidades atendidas por um código DDD brasileiro via BrasilAPI.  Retorna em JSON: estado (UF) e lista de cidades que usam aquele DDD.  Use quando o usuário perguntar de onde é um DDD, quais cidades um DDD cobre, ou descobrir o estado de um número de telefone.  NÃO use para: validar número de telefone completo, descobrir DDD a partir de cidade (a operação só é DDD → cidades), ou consultar DDDs internacionais.
- **consultar_isbn** — Consulta metadados de um livro pelo ISBN via BrasilAPI (agrega CBL, Mercado Editorial, Open Library e Google Books).  Retorna em JSON: título, subtítulo, autores, editora, ano, idioma, número de páginas, assunto/categoria, sinopse (quando disponível) e fonte do dado.  Use quando o usuário fornecer um ISBN e quiser saber sobre o livro (título, autor, editora, ano).  NÃO use para: buscar livro por título ou autor (a operação é só ISBN → metadados), validar formato sem consultar (rejeite local se não bater 10/13 dígitos), ou consultar preço/disponibilidade. Aceita ISBN-10 e ISBN-13, com ou sem hífens.
- **consultar_taxa** — Consulta o valor atual de uma taxa econômica brasileira (SELIC, CDI, IPCA) via BrasilAPI.  Retorna em JSON: nome da taxa e valor atual (% ao ano).  Use quando o usuário perguntar 'qual a SELIC hoje?', 'CDI atual?', 'inflação do IPCA?' — qualquer pergunta sobre o valor corrente de uma taxa específica.  NÃO use para: série histórica (a API devolve só o último valor), outras taxas além de SELIC/CDI/IPCA, ou consultar dólar/bolsa (não está nesta API). Pra panorama com todas as 3 taxas use listar_taxas.
- **listar_taxas** — Lista TODAS as taxas econômicas brasileiras disponíveis na BrasilAPI (SELIC, CDI, IPCA) com seus valores atuais.  Retorna em JSON um array com nome e valor (% ao ano) de cada taxa.  Use quando o usuário quiser um panorama econômico, comparar SELIC vs CDI vs IPCA, ou não souber a sigla específica.  NÃO use quando o usuário já sabe qual taxa quer — use consultar_taxa que é semanticamente mais direto. Hoje são só 3 taxas; o payload é pequeno.
- **consultar_corretora** — Consulta dados cadastrais de uma corretora de valores autorizada pela CVM (Comissão de Valores Mobiliários) via BrasilAPI.  Retorna em JSON: CNPJ, nome social, nome comercial, status (em funcionamento, cancelada, etc), endereço completo, e-mail, telefone, data de início e patrimônio quando disponível.  Use quando o usuário fornecer um CNPJ e quiser saber se é uma corretora autorizada pela CVM, ou puxar os dados cadastrais.  NÃO use para: empresas em geral (use consultar_cnpj), corretoras de seguros (CVM só regula valores mobiliários), ou buscar por nome (a API só aceita CNPJ).
- **consultar_cambio** — Consulta a cotação de câmbio oficial de uma moeda estrangeira em relação ao Real (BRL) numa data, via boletins PTAX do Banco Central (BrasilAPI).  Retorna em JSON os boletins do dia (ABERTURA, INTERMEDIÁRIO, FECHAMENTO) com cotação de compra e venda em BRL, paridade e data_hora_cotacao. A fonte NÃO expõe o dia corrente: com data omitida a tool consulta ontem (a cotação mais recente disponível), e em data sem pregão a API retorna os boletins do último dia útil anterior.  Use quando o usuário perguntar 'quanto tá o dólar?' (retorna a cotação mais recente, do dia útil anterior), 'cotação do euro em 26/06', 'quanto fechou a libra sexta-feira' — qualquer pergunta sobre valor de moeda estrangeira em reais.  NÃO use para: criptomoedas (não está nesta API), BRL (é a moeda base), série histórica (uma data por chamada), ou moedas fora das 10 suportadas — pra descobrir as moedas disponíveis use listar_moedas.
- **listar_moedas** — Lista as moedas estrangeiras com cotação disponível na BrasilAPI (boletins PTAX/BACEN).  Retorna em JSON um array com símbolo (ISO 4217), nome e tipo de cada moeda — 10 moedas: USD, EUR, GBP, JPY, CHF, CAD, AUD, DKK, NOK, SEK.  Use quando o usuário quiser saber quais moedas têm cotação disponível ou não souber o código da moeda.  NÃO use para obter a cotação em si — use consultar_cambio.
- **listar_estados** — Lista as 27 unidades federativas do Brasil (26 estados + DF) com dados do IBGE, via BrasilAPI.  Retorna em JSON um array com id (código IBGE), sigla, nome, região (Norte/Nordeste/Centro-Oeste/Sudeste/Sul) e capital de cada UF.  Use quando o usuário precisar do código IBGE de um estado, agrupar estados por região, validar siglas de UF ou saber a capital.  NÃO use para: municípios (use consultar_municipios), dados demográficos ou populacionais (não estão nesta API).
- **consultar_municipios** — Lista todos os municípios de uma UF brasileira com nome e código IBGE de 7 dígitos, via BrasilAPI.  Retorna em JSON um array de {nome, codigo_ibge}. Atenção: estados grandes retornam listas longas (SP tem 645 municípios, ~30KB) — prefira usar só quando precisar da lista ou do código de um município.  Use quando o usuário precisar do código IBGE de um município ou listar as cidades de um estado.  NÃO use para: buscar um município por nome no país inteiro (a API só filtra por UF — se souber o estado, consulte-o), endereços/CEP (use consultar_cep), ou dados populacionais.
- **consultar_dominio_br** — Consulta o status de registro de um domínio .br direto na base do registro.br (via BrasilAPI).  Retorna em JSON: status (AVAILABLE = disponível pra registro, REGISTERED = já registrado), fqdn, hosts (servidores DNS) e expires-at quando registrado, e suggestions de extensões quando disponível. O resultado nunca é cacheado — é sempre o status atual.  Use quando o usuário perguntar 'o domínio X.com.br tá livre?', 'quando expira Y.org.br?', 'quem responde pelo DNS de Z.br?'.  NÃO use para: domínios internacionais .com/.net/gTLDs (a base é só .br), dados de titular/whois completo (a API não expõe), ou hospedagem/conteúdo do site.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "brasil-data-mcp": {
    "command": "npx",
    "args": ["-y","brasil-data-mcp"]
  }
}
```

## Documentation

## What alanpcf/brasil-data-mcp MCP server does

alanpcf/brasil-data-mcp MCP server gives compatible AI clients access to Brazilian public data through 15 tools. The tools query BrasilAPI and return structured JSON for common identifiers and reference datasets. Covered sources and domains include Receita Federal company records, CEP address lookup, BACEN bank and economic data, CVM broker records, IBGE states and municipalities, Registro.br domain status, PTAX exchange bulletins, and book metadata from multiple providers.

The project also includes two MCP prompts: `analise-cnpj`, which guides a structured company analysis, and `panorama-economico`, which combines current economic rates with upcoming national holidays.

## How it works

An MCP client selects a tool based on the user's request, passes an identifier or other supported input, and receives JSON for the agent to interpret. Inputs generally accept Brazilian formats with or without punctuation where applicable, such as masked or unmasked CNPJ, CEP, and ISBN values.

The available operations are deliberately directional. CEP lookup returns an address from a CEP, but does not find a CEP from an address. Bank lookup accepts a COMPE or Febraban code, while name-based searches use the full bank list. Municipality lookup is scoped to one Brazilian state. Similar restrictions apply to DDD, ISBN, broker, and domain queries.

Exchange lookups use PTAX data for one date at a time. When no date is supplied, the service checks the previous day because the source does not expose the current day's quote. A non-trading date returns the most recent prior business-day bulletin.

## Setup and configuration

alanpcf/brasil-data-mcp MCP server runs locally through the published npm package. No credentials, API key, or environment variables are required. The direct command is:

```bash
npx -y brasil-data-mcp
```

For Claude Desktop or Cursor, configure an MCP server with `npx` as the command and `-y brasil-data-mcp` as its arguments. The README also documents a Claude Code command and a local development setup using Node.js, npm, TypeScript tooling, and the repository build output.

The server can be used with Claude Desktop, Claude Code, Cursor, Windsurf, and other MCP-compatible clients. The listed client configurations use standard stdio transport.

## Tools and capabilities

The tool set includes:

- Query company registration details by CNPJ, including status, address, CNAE, partners, capital, and contact information.
- Resolve Brazilian CEPs to state, city, neighborhood, street, and available coordinates.
- Look up banks by code or list BACEN-registered institutions with COMPE and ISPB values.
- Retrieve national holidays for a year, including movable dates, and inspect DDD coverage by state and city.
- Retrieve ISBN-10 or ISBN-13 book metadata from title through available synopsis and source.
- Read current SELIC, CDI, and IPCA values individually or as a combined list.
- Inspect CVM broker registration data by CNPJ and query PTAX quotations for supported foreign currencies.
- List Brazil's 27 federative units or retrieve all municipalities and IBGE codes for one state.
- Check whether a `.br` domain is available or registered, including DNS hosts, expiration, and suggestions when provided.

## Limitations and notes

The data scope is Brazil-specific. CNPJ lookup is not intended for CPF records or foreign companies; CEP lookup does not support international postal codes; and domain checks cover `.br` only. Holiday lookup covers national holidays, not state or municipal calendars. Economic tools provide current values rather than historical series and support SELIC, CDI, and IPCA only.

Currency lookup supports the 10 currencies listed by the service and does not cover cryptocurrencies or BRL as a foreign currency. Municipality results can be large; São Paulo, for example, has 645 entries. Domain results are not cached and represent the current status returned by the source. Invalid identifier formats should be rejected locally where the tool guidance requires validation before making a request.

_Full upstream README: https://allmcps.com/mcp/alanpcf-brasil-data-mcp/readme_