MCP Brasil — Casos de uso, Instalar & Demo ao vivo

Name: MCP Brasil MCP Server
Author: Mcp-Brasil

Por que usar

Principais recursos

Mais de 70 APIs públicas brasileiras unificadas
Sem API keys para o subconjunto de dados abertos
Cadeia de fallback ViaCEP / BrasilAPI / OpenCEP para consultas de CEP sempre bem-sucedidas
Consulta de CNPJ na Receita Federal com tratamento automático de rate limit
Taxas de câmbio diárias do BCB e série temporal da SELIC
Mantido por uma comunidade de devs brasileiros

Demo ao vivo

Como fica na prática

mcp-brasil.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": [
        "mcp-brasil"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": [
        "mcp-brasil"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": [
        "mcp-brasil"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": [
        "mcp-brasil"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-brasil",
      "command": "uvx",
      "args": [
        "mcp-brasil"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-brasil": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-brasil"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add mcp-brasil -- uvx mcp-brasil

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: MCP Brasil

Como fazer uma due diligence de uma empresa brasileira via CNPJ

👤 Vendedores B2B brasileiros, advogados, operações de fintech ⏱ ~10 min intermediate

Quando usar: Você está prestes a assinar contrato com um fornecedor e quer confirmar situação jurídica, sócios e endereço a partir de fontes oficiais.

Pré-requisitos

CNPJ da empresa — Número de 14 dígitos, com ou sem formatação

Fluxo

Consultar o perfil do CNPJ

Use o mcp-brasil. Pesquise o CNPJ 33.000.167/0001-01 e informe razão social, situação (ATIVA?), CNAE, capital social e sócios.✓ Copiado

→ Perfil estruturado com todos os campos
Verificar o endereço

Pegue o CEP registrado. Resolva via ViaCEP. A cidade confere com o que a Receita informa?✓ Copiado

→ Correspondência ou divergência sinalizada
Verificar sanções

Verifique os CPFs dos sócios em listas de sanções que este MCP expõe. Há algum resultado?✓ Copiado

→ Lista de ocorrências ou 'nenhuma restrição'

Resultado: Um memo de due diligence de 1 página sobre a contraparte, extraído de fontes oficiais em 2 minutos.

Armadilhas

A Receita aplica rate limit em consultas agressivas — A ferramenta já faz backoff com retry; para lotes acima de 20, espaçe manualmente

Combine com: filesystem

Valide um lote de endereços brasileiros (CEP) antes do envio postal

👤 Logística, e-commerce, limpeza de CRM ⏱ ~15 min beginner

Quando usar: Você tem um CSV com endereços e CEPs de clientes e quer garantir que estão corretos antes de imprimir 5.000 etiquetas.

Pré-requisitos

addresses.csv com coluna de CEP — Qualquer CSV; o Claude detectará a coluna

Fluxo

Validar

Use o mcp-brasil. Para cada CEP em /data/addresses.csv, consulte via ViaCEP. Adicione colunas de cidade, estado e bairro. Sinalize os CEPs que não resolverem.✓ Copiado

→ validated.csv com novas colunas e coluna de sinalização
Reconciliar

Para divergências entre a cidade do CRM e a cidade do ViaCEP, sugira a cidade corrigida.✓ Copiado

→ Relatório de diferenças

Resultado: Uma lista de endereços limpa com fontes citadas por linha.

Armadilhas

Alguns CEPs são 'genéricos' (abrangem uma cidade inteira) — O ViaCEP retorna esses sem bairro — isso é esperado, não é um erro

Combine com: filesystem

Extraia indicadores do IBGE para uma análise de dados focada no Brasil

👤 Analistas de dados que trabalham com mercados brasileiros ⏱ ~20 min intermediate

Quando usar: Você precisa de dados de população, PIB per capita ou IDH por município ou estado.

Fluxo

Listar indicadores

Liste os indicadores do IBGE disponíveis via mcp-brasil relacionados a PIB per capita.✓ Copiado

→ Catálogo de indicadores
Extrair série estadual

Busque o PIB per capita de todos os 27 estados, no ano mais recente. Exporte para /data/gdp.csv.✓ Copiado

→ CSV com 27 linhas
Combinar com câmbio

Converta para USD usando a taxa oficial do BCB referente ao mesmo ano. Adicione coluna.✓ Copiado

→ Coluna de USD adicionada

Resultado: Dataset estadual reproduzível, obtido do IBGE + BCB.

Armadilhas

IDs de indicadores do IBGE mudam ocasionalmente — Sempre comece pela ferramenta de catálogo; não codifique IDs diretamente

Combine com: filesystem

Combinações

Combine com outros MCPs para 10× de alavancagem

mcp-brasil + filesystem

Validar em lote CSVs de endereços ou CNPJs

Leia /data/clients.csv, valide cada CNPJ via mcp-brasil e escreva /data/clients_validated.csv.✓ Copiado

mcp-brasil + postgres

Enriquecer uma tabela Postgres com colunas de dados públicos

Para cada linha em companies, preencha ibge_municipio_id usando o CEP registrado via mcp-brasil.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
viacep	cep: str	Resolver qualquer CEP brasileiro	gratuito
cnpj_lookup	cnpj: str	Verificar uma empresa brasileira	gratuito (com rate limit da Receita)
bcb_rate	currency: str, date?: str	Necessita de uma taxa de conversão BRL oficial (ex.: para contabilidade)	gratuito
ibge_indicator	indicator_id: str, geo_level: 'br'\|'uf'\|'municipio', year?: int	Extrair estatísticas oficiais	gratuito
inpi_search	query: str, kind: 'patent'\|'trademark'	Verificação de anterioridade de marca ou patente	gratuito

Custo e limites

O que custa rodar

Cota de API: Por fonte: ViaCEP ilimitado, Receita ~3 req/min, BCB ilimitado
Tokens por chamada: 100 a 500
Monetário: Gratuito
Dica: Para trabalhos intensivos na Receita, faça cache em JSON local pelo dia

Segurança

Permissões, segredos, alcance

Armazenamento de credenciais: Nenhum para APIs de dados abertos

Saída de dados: Cada chamada vai para sua API oficial subjacente (viacep.com.br, receita, bcb, ibge, etc.)

Ao passar CPFs/CNPJs de pessoas reais, trate como PII — da mesma forma que qualquer identificador

Solução de problemas

Erros comuns e correções

Consulta de CNPJ na Receita retorna 429

Você está com rate limit. A ferramenta tenta novamente uma vez; caso contrário, aguarde 60s.

Verificar: Uma consulta única após a espera é bem-sucedida

ViaCEP retorna erro: true

O CEP não existe ou está malformado — verifique o formato ddddd-ddd

Indicador do IBGE não retorna dados para um ano

Alguns indicadores têm periodicidade plurianual; consulte o catálogo para os períodos disponíveis

Alternativas

MCP Brasil vs. outros

Alternativa	Quando usar	Troca
BrasilAPI (REST direto)	Você quer chamar um único endpoint sem uma camada MCP	A BrasilAPI sozinha é uma fonte de CEP/CNPJ; o mcp-brasil agrega mais de 70
Receita Federal direta	Você precisa dos dados de CNPJ mais autoritativos e consegue lidar com o fluxo de captcha	UX dolorosa; o mcp-brasil usa espelhos de dados abertos em cache

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills