1. 项目概述为AI智能体打开巴西公共数据宝库如果你正在开发或使用基于Claude、GPT、Copilot等大模型的AI智能体并且需要让它们访问、理解和分析巴西的公共数据那么你很可能正面临一个巨大的挑战如何高效、可靠地将数十个分散的、文档质量参差不齐的政府API集成到你的AI工作流中手动为每个API编写适配器、处理认证、管理速率限制和解析五花八门的JSON响应不仅耗时费力更会让你的项目进度陷入泥潭。mcp-brasil正是为了解决这个痛点而生。它是一个开源的Model Context Protocol (MCP) Server专门为巴西的公共数据API设计。简单来说MCP是一个由Anthropic提出的开放协议它允许AI智能体如Claude Desktop、Cursor等安全、标准化地访问外部工具和数据源。而mcp-brasil则扮演了“桥梁”的角色将巴西政府开放的41个关键数据API涵盖经济、立法、司法、健康、环境等11个领域统一封装成363个标准的MCP工具Tools。这意味着你不再需要关心某个API的端点URL长什么样、返回的JSON结构有多怪异、或者如何优雅地处理请求失败。你只需要在Claude或VS Code中配置好这个Server你的AI助手就能像调用内置函数一样用自然语言查询“给我看看圣保罗州和米纳斯吉拉斯州过去一年在健康领域的人均支出对比需要结合TCE-SP和IBGE的数据”。mcp-brasil背后的智能规划工具planejar_consulta会自动拆解这个复杂请求并行调用多个底层API并将结果整合后返回。这个项目的核心价值在于“开箱即用”和“智能集成”。它把数据获取的复杂性完全抽象掉了让开发者、数据分析师、研究员甚至普通公民都能通过最自然的对话方式挖掘巴西公共数据这座富矿。更关键的是在它封装的41个API中有38个完全无需任何API密钥即可使用剩下的3个透明度门户、DataJud、Meta广告库也只需几分钟的免费注册即可获得密钥极大地降低了使用门槛。2. 核心架构与设计哲学模块化、自动化与智能发现mcp-brasil的设计并非一蹴而就其架构清晰地反映了应对复杂集成场景时的最佳实践。理解其设计哲学对于高效使用乃至贡献代码都至关重要。2.1 基于“功能包”的模块化架构项目最核心的设计是“Package by Feature”模式。这不同于传统的按技术层次如controllers,services,models划分而是将属于同一数据领域的所有代码API客户端、数据模型、业务逻辑、MCP工具定义集中在一个独立的目录内。src/mcp_brasil/data/ ├── ibge/ # 巴西地理统计局功能包 │ ├── __init__.py # 功能元数据声明 (FEATURE_META) │ ├── server.py # 独立的FastMCP实例 │ ├── tools.py # 所有工具的实现逻辑 │ ├── client.py # 封装对IBGE API的异步HTTP调用 │ ├── schemas.py # 使用Pydantic定义严格的请求/响应模型 │ └── constants.py # API端点、城市/州代码等常量 ├── bacen/ # 巴西中央银行功能包 └── ...为什么选择这种架构高内聚低耦合每个功能包都是自包含的。修改ibge模块的API调用逻辑绝不会影响到tse最高选举法院模块。这极大提升了代码的可维护性和可测试性。便于贡献和扩展想要添加一个新的数据源例如某个州的环境数据你只需要在data/目录下创建一个新的功能包文件夹并遵循约定的文件结构即可。无需修改任何全局注册或核心路由代码。清晰的边界每个功能包负责一个明确的数据领域开发者可以快速定位和理解相关代码降低了认知负担。2.2 自动注册机制零配置集成模块化带来的一个挑战是如何让主Server自动发现并加载所有这些分散的功能包mcp-brasil通过巧妙的“自动注册”机制解决了这个问题。在每个功能包的__init__.py中你需要导出一个名为FEATURE_META的字典其中包含功能名称、描述等信息。在功能包的server.py中你需要创建一个FastMCP实例并导出为mcp。项目根目录的server.py这是你几乎不需要手动编辑的文件会在启动时动态扫描src/mcp_brasil/data/和src/mcp_brasil/agentes/目录。对于每个找到的、符合结构的功能包它会导入该包的mcp对象即那个独立的FastMCP实例。将这个子实例“挂载”到主Server上。这个过程完全是动态的。添加一个新功能包后重启Server它就会自动生效。这种设计将“声明功能”和“注册功能”的职责完全下放给了各个模块主Server只负责协调和路由符合“约定优于配置”的原则。实操心得这种自动注册模式在开发大型、可扩展的MCP Server时非常值得借鉴。它避免了在中心化的配置文件中维护一个越来越长的功能列表使得项目结构在增长过程中依然保持清晰。2.3 智能工具发现从363个工具中精准筛选一个集成了363个工具的Server如果每次交互都把全部工具列表丢给AI模型不仅会浪费大量上下文窗口Token还会导致模型困惑降低工具调用的准确性。mcp-brasil引入了“智能发现”机制来解决这个问题。通过环境变量MCP_BRASIL_TOOL_SEARCH你可以配置三种模式bm25默认这是一种经典的信息检索算法。Server会为每个工具的名称和描述建立索引。当用户提出查询时例如“查找圣保罗的犯罪数据”Server会用BM25算法快速从363个工具中检索出最相关的几个如atlas_violencia相关的工具只将这些“候选工具”提供给AI模型选择。这极大地提高了工具调用的效率和精度。code_mode实验性此模式允许开发者通过编写简单的Python代码片段以编程方式精确筛选和组合工具为高级用户提供了极大的灵活性。none禁用智能发现返回所有工具。仅在调试或需要查看全部功能时使用。背后的考量工具发现的本质是一个信息检索和相关性排序问题。BM25算法在文档检索上久经考验性能出色且无需训练非常适合这种静态的工具描述匹配场景。相比简单的关键词匹配它能更好地理解“查找议员开支”和“查询联邦议员办公室预算”之间的语义相似性。3. 核心功能深度解析与实操指南mcp-brasil的强大不仅在于集成了大量API更在于它提供了一系列“元工具”和设计模式让复杂的数据交叉分析成为可能。3.1 核心数据源与工具概览项目将41个API归类到11个主题领域以下是几个关键领域的深度解析1. 立法与透明度 (camara,senado,transparencia)这是数据最丰富、使用最频繁的领域之一。以transparencia透明度门户功能包为例它封装了54个工具。工具设计逻辑工具不是简单的一对一映射API端点。例如buscar_contratos工具内部可能整合了多个API参数如时间范围、机构、供应商、金额阈值并处理了分页逻辑最终返回一个结构清晰、可直接使用的数据列表。数据模型的重要性在schemas.py中使用Pydantic v2为每个API响应定义了严格的数据模型。这不仅仅是类型提示它确保了数据清洗自动将API返回的字符串数字转换为int或float。日期处理将2023-12-01这样的字符串自动转换为Python的date对象。验证与安全丢弃或标记不符合预期的字段防止脏数据导致下游处理错误。实操要点查询议员开支时transparenciaAPI返回的是原始票据数据。mcp-brasil的工具可能会额外提供聚合功能如按月份、按类别汇总这是在原始API之上增加的附加值。2. 经济与金融 (bacen,bndes)巴西中央银行BACEN的API提供数百个经济时间序列。mcp-brasil的bacen模块对此做了关键优化统一查询接口将不同编码的序列如Selic利率、IPCA通胀率封装成具有语义化名称的工具如get_selic_series用户无需记忆晦涩的代码。智能参数处理允许用户输入“最近12个月”、“2023年全年”等自然语言描述工具内部将其转换为API所需的精确起止日期。数据格式化将API返回的JSON时间序列数据转换为更适合AI分析和图表生成的表格格式。3. 司法与选举 (datajud,tse)这些API通常对请求频率、数据格式有更严格的要求。速率限制与重试mcp-brasil在_shared模块中实现了统一的异步HTTP客户端内置了指数退避算法的重试逻辑由MCP_BRASIL_HTTP_MAX_RETRIES控制。当遇到429 Too Many Requests或临时网络错误时会自动重试提高了鲁棒性。敏感信息处理对于司法数据工具会设计为只返回公开的、可披露的摘要信息并过滤掉个人隐私数据符合合规要求。3.2 杀手级特性智能规划与批量执行这是mcp-brasil区别于简单API聚合器的核心能力。planejar_consulta规划查询工具当用户提出一个涉及多数据源的复杂问题时例如“分析候选人A的竞选资金来源并对比其所在选区过去三年的公共合同授予情况”AI模型本身可能难以一次性拆解出所有必要步骤。工作流程AI模型首先调用planejar_consulta工具将用户的自然语言问题提交给它。内部规划该工具利用BM25检索和预定义的规则分析问题所涉及的实体候选人、选区、时间范围和所需数据维度资金来源TSE公共合同PNCP/ComprasNet生成一个执行计划。这个计划是一个JSON数组列出了需要按顺序或并行调用的具体工具及其参数。[ {tool: tse.buscar_receitas_candidato, args: {nome: Candidato A, ano: 2022}}, {tool: compras.buscar_contratos_por_municipio, args: {codigo_ibge: 3550308, ano_inicio: 2020}} ]执行AI模型或Server可以按照此计划逐步或批量调用工具。executar_lote执行批量工具有了执行计划后串行执行每个工具会非常慢。executar_lote工具允许你将计划中的多个独立查询打包成一个请求。并行化Server会使用asyncio.gather等异步机制并发地向多个底层API发起请求。统一响应所有请求完成后将结果整合成一个统一的响应返回保持了数据的关联性。性能提升对于不相互依赖的数据查询这种方式可以将耗时从各查询时间的总和降低到最慢的那个查询的时间效率提升显著。注意事项批量执行虽好但需谨慎。一是要注意目标API的并发请求限制避免触发反爬机制二是要确保批量任务中的各个查询确实是独立的一个查询的失败不应影响其他查询mcp-brasil内部实现了错误隔离。3.3 环境配置与密钥管理尽管大部分API无需密钥但为了获得完整功能正确配置是关键。获取密钥Portal da Transparência访问其网站用邮箱免费注册即刻获得密钥。这是访问联邦政府详细开支、合同数据所必需的。DataJud/CNJ需要在CNJ的DataJud平台进行免费注册用于查询全国司法过程元数据。Meta Ad Library需要拥有一个Facebook开发者账号创建应用并获取Access Token用于查询政治广告数据。配置方式以Claude Desktop为例 最佳实践是使用环境变量文件.env来管理密钥避免在配置文件中硬编码。在项目根目录或用户家目录创建.env文件TRANSPARENCIA_API_KEYseu_token_aqui DATAJUD_API_KEYseu_token_aqui META_ACCESS_TOKENseu_token_aqui修改claude_desktop_config.json通过env字段引用这些变量某些配置方式支持直接读取.env文件否则可能需要手动传递。{ mcpServers: { mcp-brasil: { command: uvx, args: [--from, mcp-brasil, python, -m, mcp_brasil.server], env: { TRANSPARENCIA_API_KEY: ${TRANSPARENCIA_API_KEY}, DATAJUD_API_KEY: ${DATAJUD_API_KEY}, META_ACCESS_TOKEN: ${META_ACCESS_TOKEN} } } } }4. 从安装到实战完整工作流演示让我们从一个具体的场景出发演示如何使用mcp-brasil完成一次完整的数据分析任务。场景一位公共政策分析师希望了解“2023年里约热内卢市在公共卫生领域的合同支出情况并找出主要的供应商”。4.1 环境安装与配置首先确保你已安装Python 3.10。推荐使用uv一个快速的Python包管理器和安装器来获得最佳体验。# 使用 pip 安装 pip install mcp-brasil # 或者更推荐使用 uv uv add mcp-brasil接下来配置你的AI客户端。这里以VS Code/Cursor为例在你的项目工作区或全局VS Code设置目录下创建或编辑.vscode/mcp.json文件。添加mcp-brasil服务器配置。假设你的API密钥已设置在系统环境变量中。{ servers: { mcp-brasil: { command: uvx, args: [--from, mcp-brasil, python, -m, mcp_brasil.server], env: { TRANSPARENCIA_API_KEY: ${env:TRANSPARENCIA_API_KEY}, DATAJUD_API_KEY: ${env:DATAJUD_API_KEY}, META_ACCESS_TOKEN: ${env:META_ACCESS_TOKEN} } } } }重启VS Code/Cursor。现在你的AI助手如Claude for VS Code就已经具备了查询巴西公共数据的能力。4.2 分步交互与智能分析现在你可以在Chat界面中直接与AI对话。第一步提出核心问题你可以直接输入“分析里约热内卢市2023年在公共卫生领域的政府合同找出支出最大的五个供应商。”第二步AI的思考与工具调用AI助手如Claude在后台会进行以下操作理解意图识别出核心实体是“里约热内卢市”Município do Rio de Janeiro时间范围是“2023年”领域是“公共卫生”Saúde Pública目标是“合同”和“供应商”。工具发现AI会向mcp-brasilServer请求可用的工具列表或通过BM25检索获得相关工具。它会发现transparencia联邦合同、compras国家采购平台、tce_rj里约州审计法院等模块可能相关。策略选择由于问题针对的是“市”级合同且属于“公共卫生”联邦透明度门户transparencia的数据可能更全面因为它聚合了所有使用联邦资金的合同。AI可能会优先选择transparencia.buscar_contratos工具。构造查询AI需要将自然语言转换为API参数。这需要知道里约热内卢市的IBGE代码3304557以及如何表示“公共卫生”。它可能会调用ibge.buscar_municipio工具来确认代码并尝试在合同查询中使用“saúde”作为关键词或功能分类代码。内部过程AI调用ibge.buscar_municipio参数为nomeRio de Janeiro, ufRJ得到响应{“codigo”: “3304557”, “nome”: “Rio de Janeiro”, ...}。然后调用transparencia.buscar_contratos参数为codigo_ibge3304557, data_inicio2023-01-01, data_fim2023-12-31, palavra_chavesaúde, pagina1。第三步处理与呈现结果Server返回合同列表后AI需要执行分析数据聚合计算每个唯一供应商nome_fornecedor的总合同金额valor_total。排序与筛选按总金额降序排列取前五名。生成洞察AI会总结“2023年里约热内卢市在公共卫生领域最大的合同供应商是X公司合同总金额Y雷亚尔涉及项目Z。其次是A公司...”建议深入方向AI可能会进一步建议“是否要查看这些供应商的历史合同记录或者比较一下其他主要城市在公共卫生上的支出比例”第四步交叉验证与深度挖掘分析师可能会追问“这些合同里有多少是通过‘紧急采购’方式进行的它们的平均金额和正常采购有区别吗” 此时AI需要利用合同数据中的modalidade_licitacao采购模式字段进行过滤和分组计算。如果原始工具没有提供这个维度的直接聚合分析师甚至可以要求AI“写一段Python代码利用pandas对刚才获取的原始合同数据进行分析”。由于数据已经通过MCP工具获取到了对话上下文中AI可以生成并执行在安全沙箱环境下相应的数据分析代码片段。4.3 使用HTTP模式与其他客户端集成除了在Claude、Cursor等内置MCP支持的客户端中使用mcp-brasil也可以作为一个独立的HTTP服务器运行供任何能够发送HTTP请求的客户端调用如自定义的Web应用、移动应用或其他AI Agent框架。# 启动HTTP服务器监听8000端口 fastmcp run mcp_brasil.server:mcp --transport http --port 8000启动后服务器会提供一个标准的MCP over HTTP端点通常是http://localhost:8000/mcp。客户端可以通过SSEServer-Sent Events或WebSocket与服务器进行双向通信调用所有工具。这对于想要构建自定义前端界面或者将巴西公共数据能力集成到自己现有AI应用中的开发者来说提供了极大的灵活性。5. 常见问题、排查与进阶技巧在实际使用和开发中你可能会遇到一些典型问题。以下是一些实录的排查经验和进阶使用方法。5.1 常见问题速查表问题现象可能原因解决方案Claude/Cursor无法连接Server1. 配置路径错误。2.uvx或python命令未在PATH中。3. Server启动报错。1. 检查claude_desktop_config.json或mcp.json的路径和格式。2. 在终端直接运行uvx --from mcp-brasil python -m mcp_brasil.server看能否启动。3. 查看客户端或终端的错误日志。工具调用返回“API无响应”或超时1. 目标政府API暂时不可用。2. 网络连接问题。3. 请求过于复杂超时时间不足。1. 稍后重试或手动访问对应API官网确认状态。2. 检查本地网络。3. 增加环境变量MCP_BRASIL_HTTP_TIMEOUT的值默认30秒。查询结果为空但预期有数据1. 查询参数不正确如错误的城市代码、日期格式。2. 该API在该参数下确实无数据。3. API的免费层级有数据范围限制。1. 使用ibge.buscar_municipios等工具确认参数。使用更宽泛的参数如扩大时间范围测试。2. 查阅该功能对应的官方API文档链接通常在源码的constants.py中。3. 部分API对历史数据查询有限制。返回数据字段不全或格式奇怪1. 官方API的响应格式发生了变更。2. 遇到了API未文档化的边缘情况。1. 这是一个开源项目欢迎在GitHub提交Issue报告。2. 可以临时使用MCP_BRASIL_TOOL_SEARCHnone模式查看原始工具列表尝试其他相关工具。智能发现BM25模式找不到预期工具工具描述与你的查询用词语义匹配度低。1. 尝试更通用或更具体的关键词。2. 切换到code_mode手动查找工具名。3. 暂时使用MCP_BRASIL_TOOL_SEARCHnone浏览全部工具。5.2 性能优化与最佳实践善用批量执行当你的分析需要从多个独立API获取数据时例如同时查询GDP、通胀率和汇率务必使用planejar_consulta和executar_lote组合。这通常能将耗时减少60%以上。缓存策略对于不常变化的数据如城市列表、议员基本信息考虑在客户端或中间层实现简单的缓存例如TTL为24小时的本地缓存可以极大减少对Server和底层API的重复请求。分页处理很多政府API返回大量数据时使用分页。mcp-brasil的工具通常已经处理了分页逻辑但如果你需要获取非常大量的数据如全国所有城市多年的合同请注意这可能会产生大量请求消耗时间和API配额。尝试通过增加过滤条件来减少单次查询的数据量。异步编程模式如果你在自定义代码中集成HTTP模式的mcp-brasilServer请确保你的客户端也是异步的如使用aiohttp以充分利用服务器的异步IO能力避免阻塞。5.3 为项目贡献新的数据源mcp-brasil的模块化设计使得添加新API变得相对简单。以下是核心步骤创建功能包结构在src/mcp_brasil/data/下创建新目录例如meu_novo_api。定义元数据在__init__.py中声明FEATURE_META。# src/mcp_brasil/data/meu_novo_api/__init__.py FEATURE_META { “name”: “meu_novo_api”, “description”: “Integração com a API do Novo Orgão Público.”, “version”: “0.1.0”, }实现核心文件constants.py: 定义API的基础URL、端点路径、常量。schemas.py: 使用Pydantic定义请求参数和响应数据的模型。这是保证数据质量的关键。client.py: 实现异步HTTP客户端处理请求、错误、重试和速率限制。继承或使用_shared中的基础客户端。tools.py: 实现具体的MCP工具函数。每个函数应有清晰的文档字符串描述其用途、参数和返回值。server.py: 创建FastMCP实例并使用mcp.tool()装饰器注册tools.py中的所有函数。最后导出mcp对象。编写测试在tests/data/meu_novo_api/下创建测试文件确保工具在各种正常和边缘情况下都能正确工作。运行完整检查在项目根目录执行make ci确保代码风格、类型检查和测试全部通过。提交Pull Request。实操心得在贡献新API时最耗时的部分往往是阅读和理解官方API文档有时它们可能不完整或已过时。建议先使用Postman或curl手动测试几个关键端点确认其实际行为后再开始编码。另外优先实现该API最核心、最常用的几个端点不必追求100%的覆盖率可以后续逐步完善。5.4 安全与合规性考量在使用mcp-brasil处理公共数据时需牢记数据来源所有数据均来自官方公开API。mcp-brasil本身不存储、修改或解释数据它只是一个中立的管道。使用限制请遵守各个原始数据提供方的服务条款和使用限制。虽然大部分是开放数据但高频、自动化的访问也可能触发限流。隐私与伦理当处理包含个人或敏感信息的数据如司法数据、竞选捐款中的个人捐赠者信息时即使数据是公开的也应在分析和呈现时考虑伦理和隐私保护原则避免进行不当关联或得出误导性结论。mcp-brasil项目本身是MIT开源协议鼓励在合规的前提下自由使用、修改和分发。它的出现显著降低了利用AI技术分析和理解巴西社会、经济、政治运行状况的门槛。无论是用于学术研究、新闻调查、商业分析还是公民监督它都提供了一个强大而便捷的技术基础。随着社区不断贡献新的数据源和工具这座连接AI与公共数据的桥梁将会变得更加坚固和宽广。