MCP Brasil — Use Cases, Install & Live Demo

Name: MCP Brasil MCP Server
Author: Mcp-Brasil

Why use it

Key features

70+ Brazilian public APIs unified
No API keys required for the open-data subset
ViaCEP / BrasilAPI / OpenCEP fallback chain so CEP lookups always succeed
Receita Federal CNPJ lookup with automatic rate-limit handling
BCB daily exchange rates and SELIC time-series
Maintained by a Brazilian dev community

Live Demo

What it looks like in practice

mcp-brasil.replay ▶ ready

0/0

Install

Pick your client

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

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

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

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

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

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

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

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

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

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

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

Add to context_servers. Zed hot-reloads on save.

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

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use MCP Brasil

How to do a CNPJ-based due diligence pass on a Brazilian counterparty

👤 Brazilian B2B sellers, lawyers, fintech ops ⏱ ~10 min intermediate

When to use: You're about to sign with a vendor and want to confirm legal status, partners, and address from official sources.

Prerequisites

CNPJ of the counterparty — 14-digit number, with or without formatting

Flow

Pull the CNPJ profile

Use mcp-brasil. Look up CNPJ 33.000.167/0001-01 and tell me legal name, status (ATIVA?), CNAE, capital social, partners.✓ Copied

→ Structured profile with all fields
Cross-check address

Take the registered CEP. Resolve via ViaCEP. Does the city match what Receita reports?✓ Copied

→ Match / mismatch flagged
Sanction check

Check the partners' CPFs against any sanction lists this MCP exposes. Anything?✓ Copied

→ List of hits or 'clean'

Outcome: A 1-page DD memo on the counterparty pulled from official sources in 2 minutes.

Pitfalls

Receita rate-limits aggressive lookups — Tool already backs off with retry; for batches > 20, space them out manually

Combine with: filesystem

Validate a batch of Brazilian addresses (CEP) before mailing

👤 Logistics, e-commerce, CRM cleanup ⏱ ~15 min beginner

When to use: You have a CSV of customer addresses and CEPs and you want them sane before printing 5000 labels.

Prerequisites

addresses.csv with CEP column — Any CSV; Claude will detect the column

Flow

Validate

Use mcp-brasil. For every CEP in /data/addresses.csv, fetch via ViaCEP. Append city, state, neighborhood. Flag CEPs that don't resolve.✓ Copied

→ validated.csv with new columns + flag column
Reconcile

For mismatches between CRM city and ViaCEP city, suggest the corrected city.✓ Copied

→ diff report

Outcome: A clean address list with sources cited per row.

Pitfalls

Some CEPs are 'genéricos' (whole city) — ViaCEP returns those without neighborhood — that's expected, not an error

Combine with: filesystem

Pull IBGE indicators for a Brazil-focused data analysis

👤 Data analysts working with Brazilian markets ⏱ ~20 min intermediate

When to use: You need population, GDP per capita, or HDI data per município or estado.

Flow

List indicators

List IBGE indicators available via mcp-brasil related to GDP per capita.✓ Copied

→ Indicator catalog
Pull state-level series

Fetch GDP per capita for all 27 estados, latest year. Output to /data/gdp.csv.✓ Copied

→ 27-row CSV
Layer with currency

Convert to USD using BCB's official rate as of the same year. Add column.✓ Copied

→ USD column appended

Outcome: Reproducible state-level dataset, sourced from IBGE + BCB.

Pitfalls

IBGE indicator IDs change occasionally — Always start from the catalog tool; don't hard-code IDs

Combine with: filesystem

Combinations

Pair with other MCPs for X10 leverage

mcp-brasil + filesystem

Batch-validate CSVs of addresses or CNPJs

Read /data/clients.csv, validate every CNPJ via mcp-brasil, write /data/clients_validated.csv.✓ Copied

mcp-brasil + postgres

Enrich a Postgres table with public-data columns

For every row in companies, fill in ibge_municipio_id using the registered CEP via mcp-brasil.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
viacep	cep: str	Resolve any Brazilian CEP	free
cnpj_lookup	cnpj: str	Verify a Brazilian company	free (rate-limited by Receita)
bcb_rate	currency: str, date?: str	Need an official BRL conversion rate (e.g. for accounting)	free
ibge_indicator	indicator_id: str, geo_level: 'br'\|'uf'\|'municipio', year?: int	Pull official statistics	free
inpi_search	query: str, kind: 'patent'\|'trademark'	Trademark / patent prior-art check	free

Cost & Limits

What this costs to run

API quota: Per source: ViaCEP unlimited, Receita ~3 req/min, BCB unlimited
Tokens per call: 100–500
Monetary: Free
Tip: For Receita-heavy jobs, batch-cache responses to local JSON for the day

Security

Permissions, secrets, blast radius

Credential storage: None for open-data APIs

Data egress: Each call goes to its underlying official API (viacep.com.br, receita, bcb, ibge, etc.)

When passing CPFs/CNPJs of real people, treat as PII — same as any identifier

Troubleshooting

Common errors and fixes

Receita CNPJ lookup returns 429

You're rate-limited. Tool retries once; otherwise wait 60s.

Verify: Single lookup after wait succeeds

ViaCEP returns erro: true

CEP doesn't exist or is malformed — check format ddddd-ddd

IBGE indicator returns no data for a year

Some indicators have multi-year cadence; query the catalog for available periodos

Alternatives

MCP Brasil vs others

Alternative	When to use it instead	Tradeoff
BrasilAPI (direct REST)	You want to call a single endpoint without an MCP layer	BrasilAPI alone is one CEP/CNPJ source; mcp-brasil aggregates 70+
Receita Federal direct	You need the most authoritative CNPJ data and can handle their captcha workflow	Painful UX; mcp-brasil uses cached open-data mirrors

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills