MCP Brasil — Cas d'usage, Installer & Démo en direct

Name: MCP Brasil MCP Server
Author: Mcp-Brasil

Pourquoi l'utiliser

Fonctionnalités clés

Plus de 70 APIs publiques brésiliennes unifiées
Pas de clés API requises pour le sous-ensemble open data
Chaîne de repli ViaCEP / BrasilAPI / OpenCEP pour que les recherches CEP réussissent toujours
Recherche CNPJ Receita Federal avec gestion automatique des limites de débit
Taux de change quotidiens BCB et séries temporelles SELIC
Maintenu par une communauté de développeurs brésiliens

Démo en direct

Aperçu en pratique

mcp-brasil.replay ▶ prêt

0/0

Installer

Choisissez votre client

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

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

Ouvrez Claude Desktop → Settings → Developer → Edit Config. Redémarrez après avoir enregistré.

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

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

Cursor utilise le même schéma mcpServers que Claude Desktop. La config projet l'emporte sur la globale.

VS Code → Cline → MCP Servers → Edit

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

Cliquez sur l'icône MCP Servers dans la barre latérale Cline, puis "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Même format que Claude Desktop. Redémarrez Windsurf pour appliquer.

~/.continue/config.json

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

Continue utilise un tableau d'objets serveur plutôt qu'une map.

~/.config/zed/settings.json

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

Ajoutez dans context_servers. Zed recharge à chaud à la sauvegarde.

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

Une seule ligne. Vérifiez avec claude mcp list. Supprimez avec claude mcp remove.

Cas d'usage

Usages concrets : MCP Brasil

Comment effectuer une due diligence basée sur le CNPJ d'une contrepartie brésilienne

👤 Vendeurs B2B brésiliens, avocats, opérations fintech ⏱ ~10 min intermediate

Quand l'utiliser : Vous êtes sur le point de signer avec un fournisseur et voulez confirmer le statut légal, les partenaires et l'adresse depuis des sources officielles.

Prérequis

CNPJ de la contrepartie — Numéro à 14 chiffres, avec ou sans formatage

Déroulement

Récupérer le profil CNPJ

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

→ Profil structuré avec tous les champs
Vérifier l'adresse

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

→ Correspondance / écart signalé
Vérification des sanctions

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

→ Liste des correspondances ou « propre »

Résultat : Un mémo de due diligence d'une page sur la contrepartie extrait de sources officielles en 2 minutes.

Pièges

La Receita limite le débit des requêtes agressives — L'outil effectue déjà des tentatives avec repli ; pour les lots > 20, espacez-les manuellement

Combiner avec : filesystem

Valider un lot d'adresses brésiliennes (CEP) avant un envoi postal

👤 Logistique, e-commerce, nettoyage CRM ⏱ ~15 min beginner

Quand l'utiliser : Vous avez un CSV d'adresses clients avec des CEP et vous voulez les nettoyer avant d'imprimer 5000 étiquettes.

Prérequis

addresses.csv avec colonne CEP — N'importe quel CSV ; Claude détectera la colonne

Déroulement

Valider

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

→ validated.csv avec nouvelles colonnes + colonne de signalement
Réconcilier

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

→ Rapport de différences

Résultat : Une liste d'adresses propre avec les sources citées par ligne.

Pièges

Certains CEP sont « génériques » (ville entière) — ViaCEP les retourne sans quartier — c'est attendu, pas une erreur

Combiner avec : filesystem

Extraire des indicateurs IBGE pour une analyse de données axée sur le Brésil

👤 Analystes de données travaillant sur les marchés brésiliens ⏱ ~20 min intermediate

Quand l'utiliser : Vous avez besoin de données de population, PIB par habitant ou IDH par município ou estado.

Déroulement

Lister les indicateurs

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

→ Catalogue d'indicateurs
Récupérer la série par état

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

→ CSV à 27 lignes
Superposer les devises

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

→ Colonne USD ajoutée

Résultat : Jeu de données reproductible au niveau des états, sourcé depuis IBGE + BCB.

Pièges

Les identifiants d'indicateurs IBGE changent occasionnellement — Toujours commencer par l'outil catalogue ; ne pas coder en dur les identifiants

Combiner avec : filesystem

Combinaisons

Associez-le à d'autres MCPs pour un effet X10

mcp-brasil + filesystem

Valider en lot des CSV d'adresses ou de CNPJ

mcp-brasil + postgres

Enrichir une table Postgres avec des colonnes de données publiques

Outils

Ce que ce MCP expose

Outil	Entrées	Quand appeler	Coût
viacep	cep: str	Résoudre n'importe quel CEP brésilien	gratuit
cnpj_lookup	cnpj: str	Vérifier une entreprise brésilienne	gratuit (limité par la Receita)
bcb_rate	currency: str, date?: str	Besoin d'un taux de conversion BRL officiel (ex. pour la comptabilité)	gratuit
ibge_indicator	indicator_id: str, geo_level: 'br'\|'uf'\|'municipio', year?: int	Extraire des statistiques officielles	gratuit
inpi_search	query: str, kind: 'patent'\|'trademark'	Vérification d'antériorité marque / brevet	gratuit

Coût et limites

Coût d'exécution

Quota d'API: Par source : ViaCEP illimité, Receita ~3 req/min, BCB illimité
Tokens par appel: 100 à 500
Monétaire: Gratuit
Astuce: Pour les tâches intensives avec la Receita, mettez en cache les réponses en JSON local pour la journée

Sécurité

Permissions, secrets, portée

Stockage des identifiants : Aucun pour les APIs open data

Sortie de données : Chaque appel va vers son API officielle sous-jacente (viacep.com.br, receita, bcb, ibge, etc.)

Lors de la transmission de CPF/CNPJ de vraies personnes, traitez-les comme des données personnelles — au même titre que tout identifiant

Dépannage

Erreurs courantes et correctifs

La recherche CNPJ Receita retourne 429

Vous êtes limité en débit. L'outil retente une fois ; sinon attendez 60s.

Vérifier : Une seule recherche après l'attente réussit

ViaCEP retourne erro: true

Le CEP n'existe pas ou est mal formaté — vérifiez le format ddddd-ddd

L'indicateur IBGE ne retourne pas de données pour une année

Certains indicateurs ont une cadence pluriannuelle ; interrogez le catalogue pour les periodos disponibles

Alternatives

MCP Brasil vs autres

Alternative	Quand l'utiliser	Compromis
BrasilAPI (REST direct)	Vous voulez appeler un seul endpoint sans couche MCP	BrasilAPI seule est une source CEP/CNPJ ; mcp-brasil agrège 70+
Receita Federal direct	Vous avez besoin des données CNPJ les plus autoritaires et pouvez gérer leur workflow captcha	UX pénible ; mcp-brasil utilise des miroirs open data en cache

Plus

Ressources

📖 Lire le README officiel sur GitHub

🐙 Voir les issues ouvertes

🔍 Parcourir les 400+ serveurs MCP et Skills