IBGE Brasil MCP

IBGE 巴西 MCP 服务

为你的 AI 助手提供实时、准确的巴西公共数据——数据来源清晰，不靠猜测。

向大模型提问 “贝洛奥里藏特在 2022 年人口普查中的人口是多少？”，它会根据训练数据给出一个看似合理的数字：可能正确，也可能已经过时，而且没有来源。ibge-br-mcp 则让你的助手实时查询 IBGE 官方 API，并返回准确数值及其来源表格和统计期。

🇧🇷 阅读葡萄牙语版

此服务实现了 Model Context Protocol（MCP），让 AI 助手能够实时、结构化地访问巴西的公共地理、人口、经济和健康数据——数据来源为 IBGE API（包括通过 IBGE 的 SIDRA 系统提供的健康指标）。

查看实际效果

用英语或葡萄牙语向你的助手提问：

• “贝洛奥里藏特在 2022 年人口普查中的人口是多少？” → ibge_cidades / ibge_censo
• “列出圣埃斯皮里图州的市镇。” → ibge_municipios
• “比较东南部各州首府的 GDP。” → ibge_comparar

答案来自 IBGE 官方 API 的实时查询——返回准确数值及其来源表格和统计期，而非根据训练数据猜测的数字。

想查看完整分析，而不只是单个答案吗？端到端演示完整演示了如何从首次调用到得出结论，回答一个真实问题——2010 年和 2022 年人口普查之间，哪个州的人口增长最多，增长的驱动因素是什么——并展示每个返回的数值。实用示例包含 7 个简短配方，其中包括通过单次调用为全部 5,570 个市镇排名。

功能

• 23 个工具，覆盖 IBGE 的所有主要数据领域——21 个 ibge_* 数据工具，以及供 ChatGPT Deep Research 使用的 search/fetch
• 每条响应都包含溯源信息块——来源、规范 URL、参考期、实际提取时间戳、可直接使用的引文和法律依据（参见数据溯源）
• 参考资源和分析提示词（MCP 目录 + 现成模板）
• 565 项自动化测试——总体覆盖率为 88%，工具覆盖率为 92%
• 自动缓存，支持配置 TTL，以获得最佳性能
• 重试机制，采用指数退避，增强网络韧性
• 全面验证所有输入参数
• 标准化错误处理，并提供实用建议
• 完整的 TypeScript 支持，采用严格类型检查

📖 文章（葡萄牙语）： Como achar a tabela certa no SIDRA — e como saber que é a certa — 如何找到正确的 SIDRA 表、用于确认的元数据、基于 2022 年人口普查数据的完整示例，以及代价最高的四个陷阱。该文章也以葡萄牙语和英语发布于网站：sidneybissoli.com。

🔌 教程：在 Claude 和 ChatGPT 中通过 MCP 查询 SIDRA——介绍如何在 claude.ai、Claude Desktop、Claude Code、ChatGPT（开发者模式和 Deep Research）、Cursor、VS Code 和 Gemini CLI 中连接此服务，然后通过一个真实查询完整演示，并展示返回的溯源信息块。葡萄牙语版。

数据溯源

从 v3.3.0 起，每条成功的工具响应都包含一个溯源信息块 （portfolio contract v1.0）， 因此每个数字都可引用、可审计、可复现。该信息块通过三个渠道输出：

1. structuredContent.provenance（可解析，模型可见）——正好包含六个键：source（所查询的 IBGE API）、source_url（可复现该查询的规范 URL）、data_vintage（来源提供的参考期；否则为 null）、retrieved_at（真实的上游提取时刻，命中缓存时也会保留，采用巴西利亚时间）、citation（“来源：IBGE — [调查/表格]、[URL]，提取于 [日期]。”），以及 license——另有 attribution，即来源 URL 的规范列表。
2. _meta 中的 br.com.sidneybissoli.ibge/provenance 和 .../attribution（供审计/UI 使用的带外镜像，不消耗模型 token）。
3. 附加到 Markdown 的简短文本页脚，供纯文本客户端使用。

IBGE API 未声明自身许可证；其法律依据是巴西的开放数据框架——Lei 12.527/2011（LAI）和 Decreto 8.777/2016（允许不受限制地重复使用、免费使用，仅要求注明来源）。统计模式响应（estatisticas=true）和 ibge_comparar 会标记为 derived，并在规范信息块中附上说明，因为这些汇总数据是在服务端根据 IBGE 原始数值计算得出的。

每个数字代表什么，以及它属于哪个版本。 SIDRA 数值本身并未说明其所属时期，也未说明它是月度变化、年初至今累计、12 个月累计、指数还是水平值——这些信息由记录的时期列及其 Variável 标签给出；每个 ibge_indicadores 条目也会固定到名称所承诺的那个变量（从 5.7.0 起；此前其中九个条目会混合表中的所有变量）。data_vintage 按 SIDRA 时期代码排序，因此 1 月至 12 月的请求会显示为“janeiro 2024–dezembro 2024”。每个数值都是 SIDRA 在 retrieved_at 时发布的版本：IBGE 会修订已发布的数据（季度 GDP、PNAD 重新加权、PIM/PMC/PMS），且不会保留旧版本。

可用工具

地方与地理

工具	描述
ibge_estados	按地区筛选并列出巴西各州
ibge_municipios	按州列出市镇，或按名称搜索
ibge_localidade	根据 IBGE 代码获取地方详情
ibge_geocodigo	解码 IBGE 代码，或按名称搜索代码
ibge_vizinhos	查找相邻市镇

统计数据（SIDRA）

工具	描述
ibge_sidra	查询 SIDRA 表（人口普查、PNAD、GDP 等）
ibge_sidra_tabelas	列出并搜索可用的 SIDRA 表（不区分重音符号；会将日常葡萄牙语表述对应到 IBGE 的官方措辞，并在响应中说明）
ibge_sidra_metadados	获取表的元数据（变量、时期、层级）
ibge_pesquisas	列出 IBGE 调查及其表格

经济与社会指标

工具	描述
ibge_indicadores	经济与社会指标（GDP、IPCA、失业率）
ibge_censo	人口普查数据（1970–2022），涵盖 16 个主题
ibge_comparar	对比各地方的指标并进行排名

市镇数据（Cidades@）

工具	描述
ibge_cidades	市镇指标（人口、HDI、人均 GDP 等）

国际数据

工具	描述
ibge_paises	按照联合国 M49 方法提供国家数据

人口统计

工具	描述
ibge_nomes	巴西姓名频率和排名

分类

工具	描述
ibge_cnae	CNAE（国家经济活动分类）

地图与地理网格

工具	描述
ibge_malhas	地理网格（GeoJSON、TopoJSON、SVG）
ibge_malhas_tema	主题区域划分包含的内容（生物群系、法定亚马逊地区、半干旱地区、沿海地区、边境地带、大都市区、RIDEs）+ 其几何数据的下载 URL

健康

工具	描述
ibge_datasaude	通过 IBGE 的 SIDRA 获取健康指标

新闻与日历

工具	描述
ibge_noticias	IBGE 新闻和新闻稿
ibge_calendario	IBGE 发布与数据收集日历

ChatGPT 深度研究

工具	描述
search	搜索 IBGE 目录（SIDRA 表、市镇、已知指标）——OpenAI 深度研究契约
fetch	返回一份目录文档（表元数据、市镇层级结构与人口、指标序列），并附上用于引用的公开 URL

这两个是唯一不带 ibge_ 前缀的工具：它们的名称由 OpenAI 契约固定。查询数据时仍请使用 ibge_* 工具。

应该使用哪个工具？

共有 23 个工具，有些工具可处理相同主题。以下是常见重叠情况的快速指南：

人口与人口统计

需求	使用
单个市镇/州的数据面板（人口、HDI、GDP……）	ibge_cidades
人口普查数据或历史序列（1970–2022）	ibge_censo
对比 2–10 个地方的单项指标并排名	ibge_comparar
宏观指标时间序列（GDP、IPCA、失业率……）	ibge_indicadores
特定 SIDRA 表／精细控制	ibge_sidra
获取整张表中的最大值／最小值／均值／中位数	使用带 estatisticas=true 的 ibge_sidra/ibge_censo/ibge_indicadores/ibge_datasaude

经济指标

需求	使用
IPCA、INPC、GDP、失业率（IBGE，主要来源）	ibge_indicadores

地方与代码

需求	使用
列出/搜索市镇	ibge_municipios
列出各州	ibge_estados
解析任意层级的名称→代码，或解码代码结构	ibge_geocodigo
获取已知代码的单个地方完整记录	ibge_localidade
相邻市镇	ibge_vizinhos

SIDRA 工作流

发现 → 检查 → 查询：ibge_pesquisas / ibge_sidra_tabelas（查找表格）→ ibge_sidra_metadados（查看其结构）→ ibge_sidra（查询）。对于常见数据，使用上面的封装工具（ibge_censo、ibge_indicadores、ibge_comparar、ibge_cidades）通常更方便。

用你自己的话提问，而不是照搬 IBGE 的说法

IBGE 使用官方统计葡萄牙语为表格命名，而 ibge_sidra_tabelas 会将你的用词与表名进行普通子字符串匹配，且区分重音符号——因此，populacao（没有波浪号，正如人们平时的输入方式）完全找不到结果；对于某个概念，日常用词与 IBGE 使用的说法不同，也会如此。在 Aggregates API 的 9,336 张表中测得（2026-09-16），此问题已于 5.1.0 修复：匹配双方都会进行规范化，每个词都必须匹配（AND），并且会将日常用词扩展为 IBGE 自己使用的词——响应会在 notas_vocabulario 中说明这一点，零结果也会提供解决办法。

你的搜索词	修复前命中数	IBGE 的说法	命中数
populacao、ocupacao、instrucao、saude、area、agua	0	população、ocupação、instrução、saúde、área、água	520、364、698、518、956、256
desemprego	4	desocupação	33
renda	72	rendimento	1,126
inflação	0	IPCA、INPC、preços	37、15、75
moradia、casa	14、101	domicílio	3,606
cidade	110	município	455
natalidade、mortes	0、1	nascidos vivos、óbitos	84、33
gênero	40	sexo	2,020
negros	0	cor ou raça	1,134
universidade、faculdade	0	ensino superior	12
luz、fábrica、tabagismo、convênio、idosos	0	energia elétrica、indústria、fumante、plano de saúde、60 anos	43、248、94、101、89

表中只列出经过测量的词对（src/vocabulario.ts，计数见表头）：你搜索的词不在目录中，而 IBGE 使用的词在目录中。IBGE 未作为汇总数据发布的内容仍会返回零，例如 turismo、aposentadoria、frota——为不存在的数据添加别名会让人误以为数据源中存在这些数据。同一张表也用于 Deep Research 的 search 索引：日常用词会作为关键词，关联到名称中包含 IBGE 用词的表格。

地图（网格）

你需要……	使用
行政边界（巴西／大区／州／市镇）	ibge_malhas
主题区域（生物群系、法定亚马逊地区、半干旱地区、大都市区）	ibge_malhas_tema（IBGE Geosserviços WFS——Malhas API 不提供这些数据）

安装

前提条件

• Node.js 22.x 或更高版本（engines.node）
• npm 或 yarn

从 npm 安装（推荐）

npm install -g ibge-br-mcp

从源码安装

# Clone the repository
git clone https://github.com/SidneyBissoli/ibge-br-mcp.git
cd ibge-br-mcp

# Install dependencies
npm install

# Build the project
npm run build

配置

远程端点（无需安装）

该服务也已托管，可通过 Streamable HTTP 使用，提供相同的工具且无需密钥：

https://ibge.sidneybissoli.com/mcp

任何接受远程 MCP 服务的客户端都可以使用它——例如在 claude.ai 中添加自定义连接器（Settings → Connectors → Add custom connector）、在 Claude Code 中运行 claude mcp add --transport http ibge https://ibge.sidneybissoli.com/mcp、在 ChatGPT 中添加应用，或使用 Cursor 和 VS Code 的 mcp.json。每个客户端的分步说明见教程。以下部分介绍通过 npx 使用本地版本。

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "ibge-br-mcp": {
      "command": "npx",
      "args": ["-y", "ibge-br-mcp"]
    }
  }
}

如果从源码安装：

{
  "mcpServers": {
    "ibge-br-mcp": {
      "command": "node",
      "args": ["/path/to/ibge-br-mcp/dist/index.js"]
    }
  }
}

Claude Code

{
  "mcpServers": {
    "ibge-br-mcp": {
      "command": "npx",
      "args": ["-y", "ibge-br-mcp"]
    }
  }
}

ChatGPT（Deep Research）

ChatGPT 深度研究（以及公司知识和通过 Responses API 实现的研究工作流）只使用恰好公开 search 和 fetch 的 MCP 服务——本服务在此基础上还提供 ibge_* 工具。将连接器指向托管端点，无需密钥：

https://ibge.sidneybissoli.com/mcp

search 会根据 SIDRA 表格、市镇和已知指标对查询进行排序，并返回 { id, title, url }；fetch 会以易读的 Markdown 格式返回文档，并附上规范的公开 URL（sidra.ibge.gov.br 或 cidades.ibge.gov.br），ChatGPT 会引用此 URL。两者都包含与其他所有工具相同的来源信息块。在 ChatGPT 的开发者模式（Settings → Security and login → Developer mode）中，任何工具都可以调用——数据查询仍应使用 ibge_* 工具。

工具使用示例

ibge_estados

列出所有巴西州。

# List all states
ibge_estados

# States in Northeast region
ibge_estados(regiao="NE")

# States sorted by abbreviation
ibge_estados(ordenar="sigla")

ibge_municipios

列出巴西市镇。

# Municipalities of São Paulo state
ibge_municipios(uf="SP")

# Search municipalities by name
ibge_municipios(busca="Campinas")

# Municipalities in MG containing "Belo"
ibge_municipios(uf="MG", busca="Belo")

ibge_cidades

查询市镇指标（类似 Cidades@ 门户）。

# Panorama of São Paulo
ibge_cidades(tipo="panorama", municipio="3550308")

# Population history
ibge_cidades(tipo="historico", municipio="3550308", indicador="populacao")

# List available research
ibge_cidades(tipo="pesquisas")

可用指标： populacao、area、densidade、pib_per_capita、idh、escolarizacao、mortalidade、salario_medio、receitas、despesas

ibge_paises

查询国际国家数据。

# List all countries
ibge_paises(tipo="listar")

# Brazil details
ibge_paises(tipo="detalhes", pais="BR")

# Search countries
ibge_paises(tipo="buscar", busca="Argentina")

# Countries in Americas
ibge_paises(tipo="listar", regiao="americas")

地区： americas、europa、africa、asia、oceania

ibge_sidra

查询 SIDRA 表格（IBGE 自动检索系统）。

# Brazil population in 2023
ibge_sidra(tabela="6579", periodos="2023")

# Population by state
ibge_sidra(tabela="6579", nivel_territorial="3", periodos="2023")

# Census 2022 for São Paulo municipality
ibge_sidra(tabela="9514", nivel_territorial="6", localidades="3550308")

常用表格：

代码	描述
6579	人口估算（年度）
9514	2022 年人口普查人口
4714	人口、领土面积和密度（2022 年人口普查）
4099	失业率（PNAD Contínua，季度）
1846	按现价计算的季度 GDP（巴西）
5938	按现价计算的市镇 GDP（年度）
6784	巴西年度 GDP 和人均 GDP

领土层级：

代码	层级
1	巴西
2	地区（北部、东北部等）
3	州（UF）
6	市镇
7	大都市区
106	卫生区
127	法定亚马逊地区
128	半干旱地区

统计模式（ibge_censo、ibge_indicadores、ibge_datasaude 也支持）： 对于最大值／最小值／平均值／中位数／分布／排名类问题，传入 estatisticas=true——服务会在分页前计算所有行的完整分布（最小值／最大值／平均值／ 中位数／标准差／带标签的百分位数），并返回 top／bottom 排名（topN，默认值为 10）。agruparPor="<column label>" 会按总和降序对分组进行排名，并为每组提供自己的简要分布。

# Which state has the largest estimated population?
ibge_sidra(tabela="6579", nivel_territorial="3", estatisticas=true)

# Census 2022 population distribution grouped by state
ibge_censo(ano="2022", tema="populacao", nivel_territorial="3", estatisticas=true, agruparPor="Unidade da Federação")

ibge_censo

查询人口普查数据（1970-2022）。

# Population Census 2022
ibge_censo(ano="2022", tema="populacao")

# Historical population series
ibge_censo(ano="todos", tema="populacao")

# Literacy by state in 2010
ibge_censo(ano="2010", tema="alfabetizacao", nivel_territorial="3")

可用主题： populacao、alfabetizacao、domicilios、idade_sexo、religiao、cor_raca、rendimento、migracao、educacao、trabalho

ibge_indicadores

查询经济和社会指标。

# GDP
ibge_indicadores(indicador="pib")

# IPCA last 12 months
ibge_indicadores(indicador="ipca", periodos="last 12")

# Unemployment by state
ibge_indicadores(indicador="desemprego", nivel_territorial="3")

# List all indicators
ibge_indicadores(indicador="listar")

可用指标：

类别	指标
经济	pib、pib_variacao、pib_per_capita、industria、comercio、servicos
价格	ipca、ipca_acumulado、inpc
劳动力	desemprego、ocupacao、rendimento、informalidade
人口	populacao、densidade
农业	agricultura、pecuaria

ibge_nomes

查询姓名频率和排名。

# Frequency of "Maria"
ibge_nomes(tipo="frequencia", nomes="Maria")

# Compare names
ibge_nomes(tipo="frequencia", nomes="João,José,Pedro")

# Ranking of names in 2000s
ibge_nomes(tipo="ranking", decada=2000)

# Female names ranking
ibge_nomes(tipo="ranking", sexo="F")

ibge_malhas

获取地理网格（地图）。

# Brazil with states
ibge_malhas(localidade="BR", resolucao="2")

# São Paulo with municipalities
ibge_malhas(localidade="SP", resolucao="5")

# Specific municipality
ibge_malhas(localidade="3550308")

# SVG format
ibge_malhas(localidade="BR", formato="svg")

分辨率级别：

值	内部划分
0	无划分（仅轮廓）
2	州
5	市镇

ibge_datasaude

查询通过 IBGE 的 SIDRA 提供的巴西健康指标（部分指标最初由 DataSUS 生成，例如死亡和出生数据）。

# Infant mortality in Brazil
ibge_datasaude(indicador="mortalidade_infantil")

# Life expectancy by state
ibge_datasaude(indicador="esperanca_vida", nivel_territorial="3")

# List indicators
ibge_datasaude(indicador="listar")

可用指标： mortalidade_infantil、esperanca_vida、nascidos_vivos、obitos、fecundidade、saneamento_agua、saneamento_esgoto、plano_saude

使用的 API

IBGE API

• 地方：servicodados.ibge.gov.br/api/v1/localidades
• 姓名：servicodados.ibge.gov.br/api/v2/censos/nomes
• 聚合数据/SIDRA：servicodados.ibge.gov.br/api/v3/agregados（此处使用 view=flat 读取 SIDRA 表；自 2026-09-15 起，apisidra.ibge.gov.br 一直受到仅限浏览器访问的 Cloudflare 挑战）
• 网格：servicodados.ibge.gov.br/api/v3/malhas
• 新闻：servicodados.ibge.gov.br/api/v3/noticias
• 人口：servicodados.ibge.gov.br/api/v1/projecoes/populacao
• CNAE：servicodados.ibge.gov.br/api/v2/cnae
• 日历：servicodados.ibge.gov.br/api/v3/calendario
• 国家：servicodados.ibge.gov.br/api/v1/paises
• 调查：servicodados.ibge.gov.br/api/v1/pesquisas

开发

# Build
npm run build

# Watch mode
npm run watch

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint
npm run lint

# Format
npm run format

# Test with MCP inspector
npm run inspector

项目结构

ibge-br-mcp/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── types.ts              # TypeScript types
│   ├── config.ts             # Configuration and constants
│   ├── cache.ts              # Request caching system
│   ├── retry.ts              # Trip to the source over @sbissoli/mcp-upstream (retry, timeout, budget, retrieval count)
│   ├── errors.ts             # Standardized error handling
│   ├── validation.ts         # Input validation helpers
│   ├── metrics.ts            # Metrics and logging
│   ├── utils/
│   │   └── formatters.ts     # Formatting utilities
│   └── tools/
│       ├── index.ts          # Tool exports
│       ├── estados.ts        # ibge_estados
│       ├── municipios.ts     # ibge_municipios
│       ├── localidade.ts     # ibge_localidade
│       ├── geocodigo.ts      # ibge_geocodigo
│       ├── censo.ts          # ibge_censo
│       ├── sidra.ts          # ibge_sidra
│       ├── sidra-tabelas.ts  # ibge_sidra_tabelas
│       ├── sidra-metadados.ts# ibge_sidra_metadados
│       ├── indicadores.ts    # ibge_indicadores
│       ├── cnae.ts           # ibge_cnae
│       ├── calendario.ts     # ibge_calendario
│       ├── comparar.ts       # ibge_comparar
│       ├── malhas.ts         # ibge_malhas
│       ├── malhas-tema.ts    # ibge_malhas_tema
│       ├── vizinhos.ts       # ibge_vizinhos
│       ├── datasaude.ts      # ibge_datasaude
│       ├── pesquisas.ts      # ibge_pesquisas
│       ├── nomes.ts          # ibge_nomes
│       ├── noticias.ts       # ibge_noticias
│       ├── paises.ts         # ibge_paises
│       └── cidades.ts        # ibge_cidades
├── tests/                    # Test files
├── dist/                     # Compiled files
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md

测试

项目包含全面的测试套件，共有 565 项测试，涵盖：

• 验证函数
• 重试机制
• 格式化工具
• 错误处理
• 缓存操作
• 使用模拟对象进行集成测试

npm test

质量保证

本项目坚持高标准的代码质量：

• 565 项自动化测试，涵盖验证、缓存、重试逻辑、格式化和集成
• 总体测试覆盖率为 88%——缓存和验证模块均超过 97%
• 使用 ESLint 进行代码检查，零警告
• 使用 Prettier 统一代码格式
• 使用 TypeScript strict mode 确保类型安全
• 通过 GitHub Actions 实现 自动化 CI/CD

在本地运行测试：

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run linter
npm run lint

可从注册表核验的表面指纹

每个版本都会在其 MCP Registry 条目中发布此版本所提供表面（initialize、工具、资源、提示词）的 sha256，以及哪些方法无需凭据即可响应。表面发生变化但版本号未更新时，构建会失败；注册表中的指纹可让客户端在自身一侧核验同样的信息。规范形式和流程： @sbissoli/mcp-surface 的 SPEC.md。 要自行核验（Node 18+，无需依赖）：

curl -sO https://raw.githubusercontent.com/SidneyBissoli/mcp-br-commons/main/packages/mcp-surface/exemplos/verify.mjs
node verify.mjs io.github.SidneyBissoli/ibge-br-mcp

许可证

MIT

作者

Sidney da Silva Pereira Bissoli

参考资料

• IBGE - 数据服务
• SIDRA - IBGE 自动检索系统
• Model Context Protocol
• MCP TypeScript SDK