mcp-brasil：把 70 個巴西公共資料源包成一個 MCP Server 的取捨

它要解決的是對接成本，不是資料品質

巴西的公共資料散在數十個互不相干的端點上：中央銀行一套、參議院一套、各州審計法院又是各自一套。每一套有自己的認證方式、分頁慣例、欄位命名與回應格式。要讓一個 LLM agent 回答「2024 年聯邦政府金額前十大的合約是誰簽的」，你得先寫十幾個 HTTP client，再把它們包成模型看得懂的 tool 描述。

mcp-brasil 把這層工作預先做完。README 說它涵蓋 70 個 feature、15 個主題領域，從經濟、立法、透明度、司法、選舉一路到環境、衛生、教育、公共安全、航空與能源。其中 66 個 API 不需要金鑰，另外 4 個需要免費註冊取得的 key。

目標讀者是誰，README 寫得算清楚：接 AI agent 的開發者。它列出的客戶端包括 Claude、GPT、Copilot，安裝章節則分別給了 Google Antigravity、Claude Desktop、VS Code / Cursor、Claude Code 與純 HTTP 的設定範例。這不是給資料記者直接用的查詢介面，也不是資料倉儲。它是一層給 agent 呼叫的適配層。

auto-registry 與 BM25 過濾：533 個 tool 怎麼不把上下文撐爆

533 個 tool 對任何模型都是災難。工具描述全部塞進 context，還沒開始回答問題就先把預算燒掉，而且模型在幾百個選項裡選錯的機率明顯上升。

專案對此有兩個機制。第一個是 README 提到的 smart discovery：用 BM25 search transform 過濾 tool 清單，只把和當前上下文相關的呈現出來。第二個是 auto-registry，README 的說法是「新增一個 feature 就是建立一個資料夾」，不需要手動註冊。這解釋了為什麼它能長到 70 個 feature 而沒有變成一坨註冊表：每個來源是獨立的模組，掃描即註冊。

另外兩個工具值得注意。planejar_consulta 用於跨來源查詢規劃，README 舉的例子是把某位眾議員的支出、投票紀錄與提案組合起來。executar_lote 則是在單次呼叫中平行發出多個查詢。這兩個工具的存在說明作者意識到：真正的問題往往不是單一 API 查得到查不到，而是要把好幾個來源拼起來才回答得了。

技術棧是 httpx async、Pydantic v2，搭配 rate limiting 與 backoff。README 沒有給出具體的速率上限數字，所以實際會不會被上游擋，只能自己對照各來源的規定。

大型資料集走 DuckDB 本地快取，而且是 opt-in

不是每個來源都適合即時打 API。SIAPA 約 81.3 萬筆不動產、TSE 2014 到 2024 的候選人與資產與得票與社群資料與 FEFC、ANP 燃料價格、INEP 的學校普查與 ENEM、ISP-RJ 的公共安全資料、ANAC 的航空器與定期航班，這些體量用 HTTP 逐頁抓並不現實。

專案的做法是把這些資料集落到本地，用 embedded DuckDB 以 SQL 查詢，並且透過環境變數 opt-in。這是一個合理的分工：小查詢走 API，大掃描走本地。但 opt-in 這個設計也意味著，如果你不設那個環境變數，這些 tool 要嘛不可用，要嘛會走比較慢的路徑。README 沒有列出完整的環境變數名稱清單，只提到「opt-in via env」，所以實際要開哪些變數得回頭翻各 feature 的說明。

這裡有一個需要自己驗證的點：本地快取的新鮮度。README 沒有說明這些資料集多久同步一次、由誰觸發、失敗時如何回報。對於 TSE 選舉資料這類一旦公布就不太變動的資料，這不成問題；對於燃料價格或公共安全統計這種會持續更新的資料，快取落後就是實質風險。

安裝：從 uvx 一行到 HTTP transport

套件在 PyPI 上，兩種安裝方式 README 都有給：pip install mcp-brasil，或 uv add mcp-brasil。

Claude Code 的使用者最省事，一行指令：claude mcp add mcp-brasil -- uvx --from mcp-brasil python -m mcp_brasil.server。其他客戶端則是在各自的設定檔裡加一個 mcpServers 區塊，command 用 uvx，args 是 --from mcp-brasil python -m mcp_brasil.server。設定檔位置依客戶端而異：Claude Desktop 是 claude_desktop_config.json，Google Antigravity 是 ~/.gemini/config/mcp_config.json 或工作區的 .agents/mcp_config.json，VS Code 與 Cursor 則是專案根目錄的 .vscode/mcp.json。

金鑰放在 env 區塊裡，README 示範的三個鍵名是 TRANSPARENCIA_API_KEY、DATAJUD_API_KEY、META_ACCESS_TOKEN。README 明確說這些 key 是選用的，沒有它們，其餘的來源照常運作。

如果要給非 MCP 原生客戶端用，可以跑 HTTP：fastmcp run mcp_brasil.server:mcp --transport http --port 8000，服務會在 http://localhost:8000/mcp。這一條對把 server 放進容器或共用主機的情境比較實際。

要注意 README 開頭寫「66 APIs 不需要金鑰」，但 Quick Start 的註解卻寫「沒有金鑰時，其餘 36 個 API 正常運作」。兩個數字對不上，可能是不同版本留下的痕跡，也可能是「36」指的是扣掉需要金鑰以外的某個子集。實際部署前值得自己確認一次。

MIT 只覆蓋程式碼，資料授權要另外讀

這是我認為這個專案最容易被誤解的地方。repository 的 license 欄位是 MIT，README 的徽章也寫 MIT (code)。但 README 用粗體標示：MIT 只涵蓋程式碼，每一個資料源有自己的授權，使用 server 還受 ACCEPTABLE_USE.md 約束，商業、新聞或決策用途之前要讀過這兩份文件。

換句話說，你把 mcp-brasil 裝進產品，不代表你可以自由使用它取回的資料。上游是巴西政府機構與審計法院，各家的再利用條款不一致。專案把這件事拆成 SOURCES.md 逐源記錄，這個做法是誠實的，但也意味著採用成本不會止於 pip install：你的法務或你自己得逐個確認你要用的那幾個來源。

README 也明確聲明這不是巴西政府或任何資料所屬機構的官方服務。這句免責在實務上有意義：出問題時沒有官方支援管道，只能回到上游 API 或專案的 issue tracker。

我不會在這裡給法律意見，只指出一個操作上的事實：如果你打算用這些資料做對外發布的內容或自動化決策，SOURCES.md 是必須逐條讀完的文件，不是附錄。

什麼情況下它會讓你失望

第一個限制是上游決定一切。這個 server 是中介層，不儲存權威資料（除了那幾個 opt-in 的本地資料集）。上游改欄位、改端點、加驗證、臨時下線，你的 agent 就會拿到錯誤或空結果，而 mcp-brasil 能做的只有回報。README 提到 rate limiting 與 backoff，但沒有承諾重試策略能覆蓋所有情況。

第二個是覆蓋不均。533 個 tool 聽起來很多，但分布相當偏斜：transparencia 一個 feature 就佔 54 個，senado 佔 26 個，camara 佔 11 個；另一端 tce_sc 只有 2 個、tce_to 只有 3 個、tce_sp 只有 3 個。如果你要查的是聖卡塔琳娜州的審計資料，能用的工具非常少。聯邦層級的資料明顯比州層級完整。

第三個是版本節奏。release 記錄顯示 v0.12.1、v0.13.0、v0.14.0 集中在 2026 年 4 月，之後到 8 月仍有 push。這種密集的小版本節奏對早期採用者是好消息，但也表示介面還在動。如果你的程式依賴特定 tool 名稱或參數，升級前要看 release notes。

第四個，也是最容易被忽略的：這個專案的價值高度取決於你的問題形狀。問「Selic 過去 12 個月走勢如何」這種單一來源的查詢，直接用中央銀行的 API 或現成圖表更快。mcp-brasil 真正省事的是跨來源的組合題，例如 README 舉的把 TCE-SP 與 IBGE 的資料交叉比較聖保羅與米納斯吉拉斯的人均衛生支出。單點查詢用它是殺雞用牛刀。

替代路線：自己寫 tool，或改用官方 MCP

最直接的替代方案是自己包。你只需要三、四個來源時，用 FastMCP 或 MCP SDK 寫幾個 tool 並不難，而且你能完全控制 tool 描述、錯誤處理與快取策略。差別在於：mcp-brasil 已經處理了 70 個來源的分頁、欄位映射與 rate limiting，你自己寫就得逐一重做，而且會踩到它已經踩過的坑。反過來說，自己寫的版本不會有 533 個 tool 需要 BM25 過濾，也不會因為某個你沒用的 feature 出問題而受影響。

另一條路是等官方。巴西政府機構陸續在推自己的 API 與資料入口，如果某個機構自己出了 MCP server，那個版本在欄位正確性與更新時效上通常會比社群中介層可靠。但這取決於個別機構的意願，短期內不會覆蓋 70 個來源。

還有一條是繞過 MCP，直接寫 ETL 把資料抓進自己的倉庫，再用 SQL 查。這對批次分析是更穩的做法，代價是你放棄了「agent 即時提問」這個互動模式。選擇的關鍵不在技術，而在你的問題是探索性的還是重複性的：探索性問題適合 mcp-brasil，重複性的報表適合 ETL。

編輯結論

如果你要讓 agent 查巴西的立法、預算、司法或選舉資料，而且能接受資料正確性由上游 API 決定，mcp-brasil 值得先跑一次再評估：用 claude mcp add mcp-brasil -- uvx --from mcp-brasil python -m mcp_brasil.server 起服務，先只測 66 個免金鑰的來源。需要 SLA、需要逐筆稽核、或要把輸出直接餵進法定決策流程的團隊不適合，因為 README 明講這不是官方服務，MIT 只覆蓋程式碼。動手前先讀 SOURCES.md 與 ACCEPTABLE_USE.md，確認你要用的那一個來源的授權條款允許你的用途。

官方來源

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