用途
ibge-br-mcp 是一个 MCP（Model Context Protocol）服务器，旨在让 AI 助手实时访问巴西 IBGE 官方 API 的地理、人口、经济与健康数据。当用户向 LLM 询问“贝洛奥里藏特在 2022 年人口普查中的人口是多少？”时，模型可能从训练数据中给出看似合理但可能过时且无来源的数字；而 ibge-br-mcp 让助手实时查询官方 IBGE API，返回精确数值以及其来源表格和参考期。
主要能力
- 23 个工具：覆盖 IBGE 主要数据领域，包括 21 个 ibge_* 数据工具，以及为 ChatGPT Deep Research 提供的 search / fetch 工具。
- 数据溯源：自 v3.3.0 起，每个成功响应都附带溯源块（portfolio contract v1.0），包含 source、source_url、data_vintage、retrieved_at、citation、license 六个键，以及 attribution。溯源信息通过三个渠道输出：structuredContent.provenance、_meta 下的 br.com.sidneybissoli.ibge/provenance 和 .../attribution，以及 Markdown 末尾的紧凑文本页脚。
- 参考资源与分析提示：提供 MCP 目录和现成模板。
- 自动化测试：565 个自动化测试，整体覆盖率 88%，工具覆盖率 92%。
- 缓存与重试：自动缓存，TTL 可配置；带指数退避的重试机制。
- 输入验证与错误处理：全面的参数验证和标准化错误处理，附带建议。
- TypeScript 支持：严格类型。
工具分类
- 地方与地理
- 统计数据（SIDRA）
- 经济与社会指标
- 市政数据（Cidades@）
- 国际数据
- 分类
- 地图与地理网格
- 新闻与日历
- ChatGPT Deep Research（search / fetch，名称由 OpenAI 合约固定，无 ibge_ 前缀）
使用方式
环境要求
Node.js 22.x 或更高版本。
从 npm 安装（推荐）
可通过 npx 运行。
远程端点（无需安装）
服务器也托管在 Streamable HTTP 上，无需密钥：https://ibge.sidneybissoli.com/mcp
适用于任何接受远程 MCP 服务器的客户端，例如 claude.ai 自定义连接器、Claude Code、ChatGPT、Cursor、VS Code 等。
Claude Desktop 配置
在 claude_desktop_config.json 中添加配置。
ChatGPT（Deep Research）
ChatGPT 深度研究仅使用暴露 search 和 fetch 的 MCP 服务器。将连接器指向托管端点，无需密钥。search 对 SIDRA 表、市政当局和已知指标进行查询排名，返回 { id, title, url }；fetch 返回可读 Markdown 文档及规范公共 URL。
适用场景
- 查询巴西各州、市镇列表及代码。
- 查询市政指标（人口、面积、密度、人均 GDP、IDH、入学率、死亡率、平均工资、收入、支出）。
- 查询国际国家数据（美洲、欧洲、非洲、亚洲、大洋洲）。
- 查询 SIDRA 表（IBGE 自动恢复系统）。
- 查询人口普查数据（1970-2022），主题包括人口、识字、家庭、年龄性别、宗教、种族、收入、迁移、教育、工作。
- 查询经济与社会指标。
- 查询姓名频率和排名。
- 获取地理网格（地图）。
- 查询通过 IBGE SIDRA 提供的巴西健康指标（部分由 DataSUS 制作，如死亡率和出生）。
- 统计模式：对于最大/最小/均值/中位数/分布/排名问题，传递 estatisticas=true，服务器在分页前计算完整分布并返回 top/bottom 排名。
限制
- IBGE API 本身未声明许可证；法律框架为巴西开放数据框架（Lei 12.527/2011 和 Decreto 8.777/2016），允许不受限制的再利用和免费使用，义务仅限于注明来源。
- 统计模式响应和 ibge_comparar 被标记为派生数据，因为聚合值由服务器端从原始 IBGE 值计算。
- 每个值是 SIDRA 在 retrieved_at 时发布的版本；IBGE 会修订已发布数字且不保留早期版本。
- 词汇表仅包含已测量的配对；IBGE 未作为聚合发布的概念（如 turismo、aposentadoria、frota）仍返回零结果。
- 自 2026-09-15 起，apisidra.ibge.gov.br 处于仅浏览器可访问的 Cloudflare 挑战之后，SIDRA 表通过 servicodados.ibge.gov.br/api/v3/agregados 以 view=flat 读取。
- 项目结构包含 565 个测试，覆盖验证、重试、格式化、缓存和集成。
- 质量保证：ESLint 零警告、Prettier、TypeScript 严格模式、GitHub Actions CI/CD。
- 每个版本在 MCP Registry 条目中发布其服务的表面指纹（initialize、tools、resources、prompts）的 sha256，以及哪些方法无需凭据即可应答。
