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

Name: MCP Brasil MCP Server
Author: Mcp-Brasil

Por qué usarlo

Características clave

Más de 70 APIs públicas brasileñas unificadas
Sin API keys para el subconjunto de datos abiertos
Cadena de fallback ViaCEP / BrasilAPI / OpenCEP para que las consultas de CEP siempre funcionen
Consulta de CNPJ en Receita Federal con manejo automático de límite de tasa
Tipos de cambio diarios del BCB y series temporales de la SELIC
Mantenido por la comunidad de desarrolladores brasileños

Demo en vivo

Cómo se ve en la práctica

mcp-brasil.replay ▶ listo

0/0

Instalar

Elige tu cliente

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

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

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

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

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

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

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

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

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

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

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

Añádelo a context_servers. Zed recarga en caliente al guardar.

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

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: MCP Brasil

Cómo hacer una pasada de due diligence basada en CNPJ sobre una contraparte brasileña

👤 Vendedores B2B brasileños, abogados, operaciones fintech ⏱ ~10 min intermediate

Cuándo usarlo: Estás a punto de firmar con un proveedor y quieres confirmar estado legal, socios y dirección desde fuentes oficiales.

Requisitos previos

CNPJ de la contraparte — Número de 14 dígitos, con o sin formato

Flujo

Obtener el perfil CNPJ

Usa mcp-brasil. Busca el CNPJ 33.000.167/0001-01 y dime razón social, situación (¿ATIVA?), CNAE, capital social y socios.✓ Copiado

→ Perfil estructurado con todos los campos
Verificar la dirección

Toma el CEP registrado. Resuélvelo mediante ViaCEP. ¿La ciudad coincide con lo que reporta Receita?✓ Copiado

→ Coincidencia o discrepancia señalada
Verificar sanciones

Comprueba los CPFs de los socios contra cualquier lista de sanciones que exponga este MCP. ¿Hay algún resultado?✓ Copiado

→ Lista de coincidencias o 'sin registros'

Resultado: Un memo de DD de 1 página sobre la contraparte, obtenido desde fuentes oficiales en 2 minutos.

Errores comunes

Receita limita la tasa en consultas agresivas — La herramienta ya hace retroceso con reintento; para lotes > 20, espácialos manualmente

Combinar con: filesystem

Valida un lote de direcciones brasileñas (CEP) antes de un envío postal

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

Cuándo usarlo: Tienes un CSV de direcciones y CEPs de clientes y quieres que estén correctos antes de imprimir 5000 etiquetas.

Requisitos previos

addresses.csv con columna CEP — Cualquier CSV; Claude detectará la columna

Flujo

Validar

Usa mcp-brasil. Para cada CEP en /data/addresses.csv, consulta mediante ViaCEP. Añade ciudad, estado y barrio. Señala los CEPs que no se resuelvan.✓ Copiado

→ validated.csv con columnas nuevas y columna de flag
Reconciliar

Para las discrepancias entre la ciudad del CRM y la ciudad de ViaCEP, sugiere la ciudad corregida.✓ Copiado

→ Informe de diferencias

Resultado: Una lista de direcciones limpia con fuentes citadas por fila.

Errores comunes

Algunos CEPs son 'genéricos' (toda una ciudad) — ViaCEP los devuelve sin barrio — eso es lo esperado, no un error

Combinar con: filesystem

Obtén indicadores del IBGE para un análisis de datos enfocado en Brasil

👤 Analistas de datos que trabajan con mercados brasileños ⏱ ~20 min intermediate

Cuándo usarlo: Necesitas datos de población, PIB per cápita o IDH por município o estado.

Flujo

Listar indicadores

Lista los indicadores del IBGE disponibles mediante mcp-brasil relacionados con el PIB per cápita.✓ Copiado

→ Catálogo de indicadores
Obtener serie a nivel estatal

Obtén el PIB per cápita para los 27 estados, último año disponible. Exporta a /data/gdp.csv.✓ Copiado

→ CSV de 27 filas
Combinar con tipo de cambio

Convierte a USD usando el tipo oficial del BCB del mismo año. Añade la columna.✓ Copiado

→ Columna en USD añadida

Resultado: Dataset reproducible a nivel estatal, con fuentes del IBGE + BCB.

Errores comunes

Los IDs de indicadores del IBGE cambian ocasionalmente — Empieza siempre desde la herramienta de catálogo; no hardcodees IDs

Combinar con: filesystem

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

mcp-brasil + filesystem

Validar en lote CSVs de direcciones o CNPJs

mcp-brasil + postgres

Enriquecer una tabla Postgres con columnas de datos públicos

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
viacep	cep: str	Resolver cualquier CEP brasileño	gratis
cnpj_lookup	cnpj: str	Verificar una empresa brasileña	gratis (con límite de tasa de Receita)
bcb_rate	currency: str, date?: str	Obtener un tipo de cambio BRL oficial (p. ej. para contabilidad)	gratis
ibge_indicator	indicator_id: str, geo_level: 'br'\|'uf'\|'municipio', year?: int	Obtener estadísticas oficiales	gratis
inpi_search	query: str, kind: 'patent'\|'trademark'	Búsqueda de arte previo en marcas y patentes	gratis

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Por fuente: ViaCEP ilimitado, Receita ~3 req/min, BCB ilimitado
Tokens por llamada: 100–500
Monetario: Gratis
Consejo: Para trabajos intensivos con Receita, guarda las respuestas en JSON local para el día

Seguridad

Permisos, secretos, alcance

Almacenamiento de credenciales: Ninguno para las APIs de datos abiertos

Salida de datos: Cada llamada va a su API oficial subyacente (viacep.com.br, receita, bcb, ibge, etc.)

Al pasar CPFs o CNPJs de personas reales, trátelos como PII — igual que cualquier identificador

Resolución de problemas

Errores comunes y soluciones

Consulta CNPJ de Receita devuelve 429

Estás limitado por tasa. La herramienta reintenta una vez; en caso contrario espera 60 s.

Verificar: Una consulta individual tras la espera tiene éxito

ViaCEP devuelve erro: true

El CEP no existe o tiene formato incorrecto — verifica el formato ddddd-ddd

El indicador del IBGE no devuelve datos para un año

Algunos indicadores tienen cadencia plurianual; consulta el catálogo para ver los periodos disponibles

Alternativas

MCP Brasil vs otros

Alternativa	Cuándo usarla	Contrapartida
BrasilAPI (REST directo)	Quieres llamar a un único endpoint sin capa MCP	BrasilAPI sola es una fuente de CEP/CNPJ; mcp-brasil agrega más de 70
Receita Federal directo	Necesitas los datos de CNPJ más autoritativos y puedes manejar su flujo con captcha	UX complicada; mcp-brasil usa espejos de datos abiertos en caché

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills