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