mcp-brasil : exposer 70 sources publiques brésiliennes à un agent MCP

Ce que le dépôt résout, et pour qui

Un agent conversationnel qui doit répondre à une question sur les finances publiques brésiliennes se heurte à un mur pratique : chaque institution publie ses données selon son propre schéma, son propre format de pagination et ses propres règles d'authentification. Le dépôt part de ce constat et propose une couche unique. Le README annonce 533 tools, 131 resources et 102 prompts répartis sur 70 features et 15 domaines : économie, législatif, transparence, judiciaire, électoral, environnement, santé, éducation, sécurité publique, achats publics, fiscal infranational, aviation, énergie.

Le public visé est précis : développeurs qui construisent des agents sur Claude, GPT ou Copilot et veulent brancher des données brésiliennes sans maintenir eux-mêmes une collection de clients HTTP. Le README précise que 66 API ne demandent aucune clé et que 4 en exigent une gratuite, obtenue par un enregistrement présenté comme prenant une minute. Ce ratio est l'argument central du projet. Il signifie aussi que la qualité varie d'une source à l'autre, puisque toutes ne sont pas documentées de la même façon côté institution.

Le mécanisme : auto-registry, cache DuckDB et filtrage BM25

Trois mécanismes structurent le serveur. Le premier est l'auto-registry : d'après le README, ajouter une feature consiste à créer un dossier, sans configuration manuelle. C'est un choix d'architecture qui explique en partie le nombre élevé de tools, et qui déplace le coût de maintenance vers la discipline des contributeurs plutôt que vers un fichier central.

Le deuxième est le cache local pour les jeux de données volumineux. Le README cite SIAPA avec environ 813 000 immeubles, les données TSE de 2014 à 2024 (candidats, biens, votes, réseaux sociaux, FEFC), les prix de carburants ANP, le Censo Escolar et l'ENEM de l'INEP, ISP-RJ pour la sécurité publique, et ANAC pour les aéronefs et vols réguliers. Ces données sont interrogeables en SQL via DuckDB embarqué, et le README indique que l'activation se fait par variable d'environnement, en opt-in. Autrement dit, rien n'est téléchargé tant que vous ne l'avez pas demandé.

Le troisième est la recherche BM25. Le README la décrit comme un filtre qui réduit les 533 tools à ceux pertinents pour le contexte courant. Sans ce filtre, un agent recevrait une liste d'outils si longue que la sélection deviendrait elle-même un problème. Le serveur expose par ailleurs deux outils de composition : planejar_consulta, qui construit des plans d'exécution combinant plusieurs API (l'exemple donné est celui des dépenses d'un député croisées avec ses votes et ses propositions), et executar_lote, qui lance des requêtes en parallèle dans un seul appel. La pile technique annoncée est httpx async, Pydantic v2 et un rate limiting avec backoff.

Mise en route : pip, uvx et quatre fichiers de configuration

L'installation tient en une commande : pip install mcp-brasil, ou uv add mcp-brasil. Pour un client MCP, le README fournit des blocs JSON à coller. Pour Claude Desktop, le fichier est claude_desktop_config.json ; pour Google Antigravity, il s'agit de mcp_config.json, accessible via MCP Servers puis Manage MCP Servers puis View raw config, ou directement à ~/.gemini/config/mcp_config.json en global et .agents/mcp_config.json en workspace ; pour VS Code et Cursor, le fichier est .vscode/mcp.json à la racine du projet. Dans les trois cas, le bloc déclare une commande uvx avec les arguments --from, mcp-brasil, python, -m, mcp_brasil.server, et un objet env contenant TRANSPARENCIA_API_KEY, DATAJUD_API_KEY et META_ACCESS_TOKEN.

Pour Claude Code, la ligne est plus directe : claude mcp add mcp-brasil -- uvx --from mcp-brasil python -m mcp_brasil.server. Pour les autres clients, le transport HTTP passe par fastmcp run mcp_brasil.server:mcp --transport http --port 8000, le serveur étant alors disponible sur http://localhost:8000/mcp.

Un point mérite attention : le README affirme d'abord que 66 API ne requièrent pas de clé, puis, dans la section Claude Desktop, que sans les clés, les 36 API restantes fonctionnent normalement. Les deux formulations ne se recoupent pas exactement. Avant de dimensionner un déploiement, il vaut mieux considérer les clés comme optionnelles mais utiles, et vérifier dans la liste des tools exposés lesquels restent indisponibles sans elles.

Le cas où ce n'est pas le bon outil

La couverture large a un revers : elle masque l'hétérogénéité des sources. Le dépôt agrège des API fédérales, des portails de tribunaux de comptes régionaux et des jeux de données téléchargeables. Ces sources n'ont ni la même fraîcheur, ni la même stabilité de schéma, ni le même régime de licence. Le README le dit sans détour : la licence MIT couvre uniquement le code, chaque source de données a sa propre licence dans SOURCES.md, et l'usage du serveur est soumis à ACCEPTABLE_USE.md.

C'est la limite la plus concrète du projet. Un outil MCP qui répond correctement sur une API fédérale peut échouer silencieusement sur une source régionale moins maintenue, et l'agent n'aura aucun moyen de distinguer une absence de résultat d'une panne de source. Pour un usage journalistique ou décisionnel, où une donnée fausse coûte plus cher qu'une donnée absente, il faut donc prévoir une vérification humaine sur les résultats critiques.

Le projet se présente explicitement comme indépendant : le README indique qu'il n'est ni un service officiel du gouvernement brésilien, ni un service d'une des institutions dont il rend les données accessibles. Cette précision a une conséquence pratique : en cas de changement de contrat d'API côté institution, il n'existe pas de canal officiel de support, seulement le dépôt.

Face à un client écrit à la main

L'alternative la plus directe n'est pas un autre serveur MCP, c'est un client HTTP écrit pour les deux ou trois API réellement utilisées. La différence d'approche est nette. Un client dédié vous laisse choisir la gestion d'erreurs, la politique de retry et la forme exacte des données renvoyées à l'agent ; vous payez cela en travail de maintenance, un par fournisseur, à chaque évolution de schéma.

mcp-brasil inverse le compromis : vous obtenez immédiatement 533 tools et un cache SQL pour les gros volumes, mais vous héritez des choix d'abstraction du projet, de son rythme de mise à jour et de ses conventions de nommage d'outils. Le README ne documente pas de mécanisme d'extension pour remplacer une feature existante par une implémentation maison, ce qui veut dire que la personnalisation fine se fait probablement en amont du serveur, pas dedans.

Le calcul dépend donc du nombre de sources. Pour une seule API, un client maison reste plus prévisible. À partir de cinq ou six sources, la couche commune commence à compenser son coût d'opacité, à condition d'accepter de ne pas contrôler chaque détail de la requête sous-jacente.

Maintenance, versions et implications de licence

Le dépôt n'est pas archivé. Les dernières versions listées sont v0.14.0 et v0.13.0, toutes deux datées du 24 avril 2026, et v0.12.1 du 14 avril 2026. Deux publications le même jour, à moins d'une heure d'intervalle, suggèrent des correctifs rapprochés plutôt qu'un cycle lent et espacé. Le dernier push enregistré est daté du 19 août 2026, soit environ quatre mois après la dernière version listée. Le matériel fourni ne permet pas de dire si cette période correspond à un ralentissement ou à un travail non publié.

La numérotation reste en 0.x, ce qui signifie que des ruptures d'interface entre versions mineures sont possibles. Un déploiement qui épingle la version dans son fichier de configuration évite ce risque. Pour la mise à jour, les commandes du README passent par uvx, qui résout la version à l'exécution : sans épinglage explicite, un redémarrage du client peut changer la version du serveur sans que personne ne l'ait décidé.

Sur le plan juridique, la licence MIT s'applique au code et autorise la réutilisation et la modification. Elle ne dit rien des données. Le README renvoie à SOURCES.md pour les licences par source et à ACCEPTABLE_USE.md pour les conditions d'usage, en demandant de lire les deux avant tout usage commercial, journalistique ou décisionnel. Cette séparation entre licence logicielle et licence de données est correcte, mais elle implique que la conformité d'un déploiement se vérifie source par source, pas au niveau du dépôt. Ce texte ne constitue pas un avis juridique.

Conclusion éditoriale

mcp-brasil convient aux équipes qui interrogent déjà des données publiques brésiliennes et veulent les rendre accessibles à un agent sans écrire un client par API. Il ne convient pas à un usage décisionnel automatisé sans relecture : la licence MIT ne couvre que le code, et ACCEPTABLE_USE.md impose des conditions que chaque source redéfinit dans SOURCES.md. Avant toute intégration, vérifier dans SOURCES.md la licence de la source précise que vous allez interroger, puis lancer le serveur avec les clés TRANSPARENCIA_API_KEY et DATAJUD_API_KEY pour confirmer que les outils attendus apparaissent bien dans la liste exposée.

Sources officielles

1. Issues
2. License: MIT
3. Mcp-Brasil/mcp-brasil on GitHub
4. README
5. Releases