Ibge Br MCP

🚀 ibge-br-mcp

这是一个用于访问巴西地理与统计研究所（IBGE）公共API的MCP服务器，借助它，AI助手能够查询巴西的地理、人口和统计数据。

🚀 快速开始

该服务器实现了 模型上下文协议（MCP），以提供对IBGE公共API的访问，使AI助手能够查询巴西的地理、人口和统计数据。

✨ 主要特性

• 23个专业工具：涵盖了IBGE的所有主要数据领域。
• 227个自动化测试：核心覆盖率超过97%。
• 自动缓存：可配置TTL以实现最佳性能。
• 重试机制：采用指数退避策略，确保网络弹性。
• 全面验证：对所有输入参数进行验证。
• 标准化错误处理：提供有用的建议。
• 完整的TypeScript支持：采用严格类型。

📦 安装指南

前提条件

• Node.js 18.x 或更高版本
• npm 或 yarn

通过npm安装（推荐）

npm install -g ibge-br-mcp

从源代码安装

# 克隆仓库
git clone https://github.com/SidneyBissoli/ibge-br-mcp.git
cd ibge-br-mcp

# 安装依赖
npm install

# 构建项目
npm run build

💻 使用示例

基础用法

ibge_estados

列出所有巴西州：

# 列出所有州
ibge_estados

# 东北部地区的州
ibge_estados(regiao="NE")

# 按缩写排序的州
ibge_estados(ordenar="sigla")

ibge_municipios

列出巴西的城市：

# 圣保罗州的城市
ibge_municipios(uf="SP")

# 按名称搜索城市
ibge_municipios(busca="Campinas")

# 米纳斯吉拉斯州包含 "Belo" 的城市
ibge_municipios(uf="MG", busca="Belo")

ibge_cidades

查询城市指标（类似于Cidades@门户）：

# 圣保罗的概况
ibge_cidades(tipo="panorama", municipio="3550308")

# 人口历史
ibge_cidades(tipo="historico", municipio="3550308", indicador="populacao")

# 列出可用的研究
ibge_cidades(tipo="pesquisas")

可用指标：populacao（人口）, area（面积）, densidade（密度）, pib_per_capita（人均GDP）, idh（人类发展指数）, escolarizacao（教育程度）, mortalidade（死亡率）, salario_medio（平均工资）, receitas（收入）, despesas（支出）

ibge_paises

查询国际国家数据：

# 列出所有国家
ibge_paises(tipo="listar")

# 巴西的详细信息
ibge_paises(tipo="detalhes", pais="BR")

# 搜索国家
ibge_paises(tipo="buscar", busca="Argentina")

# 美洲的国家
ibge_paises(tipo="listar", regiao="americas")

地区：americas（美洲）, europa（欧洲）, africa（非洲）, asia（亚洲）, oceania（大洋洲）

ibge_sidra

查询SIDRA表格（IBGE的自动恢复系统）：

# 2023年巴西的人口
ibge_sidra(tabela="6579", periodos="2023")

# 按州划分的人口
ibge_sidra(tabela="6579", nivel_territorial="3", periodos="2023")

# 2022年圣保罗市的人口普查
ibge_sidra(tabela="9514", nivel_territorial="6", localidades="3550308")

常用表格：

地域级别：

ibge_censo

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

# 2022年人口普查
ibge_censo(ano="2022", tema="populacao")

# 历史人口系列
ibge_censo(ano="todos", tema="populacao")

# 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")

# 过去12个月的IPCA
ibge_indicadores(indicador="ipca", periodos="last 12")

# 各州的失业率
ibge_indicadores(indicador="desemprego", nivel_territorial="3")

# 列出所有指标
ibge_indicadores(indicador="listar")

可用指标：

ibge_nomes

查询姓名频率和排名：

# "Maria" 的频率
ibge_nomes(tipo="frequencia", nomes="Maria")

# 比较姓名
ibge_nomes(tipo="frequencia", nomes="João,José,Pedro")

# 2000年代的姓名排名
ibge_nomes(tipo="ranking", decada=2000)

# 女性姓名排名
ibge_nomes(tipo="ranking", sexo="F")

ibge_malhas

获取地理网格（地图）：

# 包含各州的巴西地图
ibge_malhas(localidade="BR", resolucao="2")

# 包含城市的圣保罗地图
ibge_malhas(localidade="SP", resolucao="5")

# 特定城市
ibge_malhas(localidade="3550308")

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

分辨率级别：

bcb

查询巴西中央银行的数据：

# 过去12个月的SELIC利率
bcb(indicador="selic", ultimos=12)

# 2023年的IPCA
bcb(indicador="ipca", dataInicio="01/01/2023", dataFim="31/12/2023")

# 过去30天的美元汇率
bcb(indicador="dolar_venda", ultimos=30)

可用指标：selic（基准利率）, cdi（银行间存款利率）, tr（实际利率）, ipca（全国广义消费者物价指数）, ipca_acum（累计IPCA）, igpm（广义市场价格指数）, inpc（全国消费者物价指数）, dolar_compra（美元买入价）, dolar_venda（美元卖出价）, euro（欧元）, desemprego（失业率）

datasaude

通过IBGE/DataSUS查询健康指标：

# 巴西的婴儿死亡率
datasaude(indicador="mortalidade_infantil")

# 各州的预期寿命
datasaude(indicador="esperanca_vida", nivel_territorial="3")

# 列出指标
datasaude(indicador="listar")

可用指标：mortalidade_infantil（婴儿死亡率）, esperanca_vida（预期寿命）, nascidos_vivos（活产数）, obitos（死亡数）, fecundidade（生育率）, saneamento_agua（供水卫生）, saneamento_esgoto（污水处理）, plano_saude（医疗保险）

📚 详细文档

可用工具

地区与地理

统计数据（SIDRA）

经济与社会指标

城市数据（Cidades@）

国际数据

人口统计

分类

地图与地理网格

外部数据（BCB和健康）

新闻与日历

配置

Claude Desktop

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

{
  "mcpServers": {
    "ibge-br-mcp": {
      "command": "npx",
      "args": ["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": ["ibge-br-mcp"]
    }
  }
}

使用的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
• SIDRA API：apisidra.ibge.gov.br/values
• 网格：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

外部API

• 中央银行（BCB）：api.bcb.gov.br/dados/serie/bcdata.sgs - 利率、汇率、通货膨胀

开发

# 构建
npm run build

# 监听模式
npm run watch

# 运行测试
npm test

# 在监听模式下运行测试
npm run test:watch

# 代码检查
npm run lint

# 代码格式化
npm run format

# 使用MCP检查器进行测试
npm run inspector

项目结构

ibge-br-mcp/
├── src/
│   ├── index.ts              # 主MCP服务器
│   ├── types.ts              # TypeScript类型
│   ├── config.ts             # 配置和常量
│   ├── cache.ts              # 请求缓存系统
│   ├── retry.ts              # 指数退避重试
│   ├── errors.ts             # 标准化错误处理
│   ├── validation.ts         # 输入验证辅助工具
│   ├── metrics.ts            # 指标和日志记录
│   ├── utils/
│   │   └── formatters.ts     # 格式化工具
│   └── tools/
│       ├── index.ts          # 工具导出
│       ├── estados.ts        # ibge_estados
│       ├── municipios.ts     # ibge_municipios
│       ├── localidade.ts     # ibge_localidade
│       ├── geocodigo.ts      # ibge_geocodigo
│       ├── censo.ts          # ibge_censo
│       ├── populacao.ts      # ibge_populacao
│       ├── 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
│       ├── bcb.ts            # bcb
│       ├── datasaude.ts      # datasaude
│       ├── pesquisas.ts      # ibge_pesquisas
│       ├── nomes.ts          # ibge_nomes
│       ├── noticias.ts       # ibge_noticias
│       ├── paises.ts         # ibge_paises
│       └── cidades.ts        # ibge_cidades
├── tests/                    # 测试文件
├── dist/                     # 编译后的文件
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md

测试

该项目包含一个全面的测试套件，有227个测试，涵盖：

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

npm test

质量保证

该项目保持了较高的代码质量标准：

• 227个自动化测试：涵盖验证、缓存、重试逻辑、格式化和集成。
• 97%以上的测试覆盖率：核心模块（缓存、验证、错误、类型）。
• ESLint：代码检查，零警告。
• Prettier：一致的代码格式化。
• TypeScript严格模式：类型安全。
• 自动化CI/CD：通过GitHub Actions实现。

在本地运行测试：

# 运行所有测试
npm test

# 运行带覆盖率的测试
npm run test:coverage

# 运行代码检查
npm run lint

📄 许可证

本项目采用MIT许可证。

作者

Sidney Bissoli

参考资料

• IBGE - 数据服务
• SIDRA - IBGE自动恢复系统
• 模型上下文协议
• MCP TypeScript SDK