ibge-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Cestari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# IBGE MCP Server
+
+Servidor MCP que expõe as APIs públicas do IBGE (agregados e localidades) como ferramentas para agentes de IA.
+
+## Ferramentas
+
+| Ferramenta            | Descrição                                                          |
+| --------------------- | ------------------------------------------------------------------ |
+| `pesquisas`           | Lista as pesquisas do IBGE                                         |
+| `agregados`           | Lista os agregados de uma pesquisa                                 |
+| `agregado-metadados`  | Variáveis, níveis territoriais e períodos de um agregado           |
+| `agregado-dados`      | Busca os dados de um agregado                                      |
+| `localidades`         | Descobre o id de um estado ou cidade                               |
+| `data-hora`           | Data e hora atuais no fuso de Brasília                             |
+
+## Requisitos
+
+- Node.js 20+
+
+## Instalação
+
+Como pacote publicado no npm:
+
+```bash
+npx ibge-mcp-server
+```
+
+Para desenvolver localmente:
+
+```bash
+npm install
+```
+
+## Uso
+
+Desenvolvimento:
+
+```bash
+npm run dev
+```
+
+Produção:
+
+```bash
+npm run build
+npm start
+```
+
+Inspecionar as ferramentas no MCP Inspector:
+
+```bash
+npm run inspect
+```
+
+## Configuração
+
+Crie um arquivo `.env` na raiz do projeto. Todas as variáveis são opcionais e têm valores padrão:
+
+| Variável                | Padrão                                                  |
+| ----------------------- | ------------------------------------------------------- |
+| `TRANSPORT_TYPE`        | `stdio` (ou `httpStream`)                                |
+| `PORT`                  | `3000` (usado apenas com `httpStream`)                   |
+| `IBGE_API_AGREGADOS`    | `https://servicodados.ibge.gov.br/api/v3/agregados`      |
+| `IBGE_API_LOCALIDADES`  | `https://servicodados.ibge.gov.br/api/v1/localidades`    |
+
+## Conectando a um cliente MCP
+
+```json
+{
+  "mcpServers": {
+    "ibge": {
+      "command": "npx",
+      "args": ["-y", "ibge-mcp-server"]
+    }
+  }
+}
+```
+
+Usando o código local:
+
+```json
+{
+  "mcpServers": {
+    "ibge": {
+      "command": "npx",
+      "args": ["tsx", "src/index.ts"],
+      "cwd": "/caminho/para/ibge-mcp-server"
+    }
+  }
+}
+```
+
+## Testes
+
+Os testes são avaliações que rodam um agente real contra o servidor e comparam a resposta com o resultado esperado. Eles usam um `.env` próprio: copie `test/.env.test.example` para `test/.env.test` e preencha as chaves.
+
+```bash
+npm test                  # runner padrão definido em TEST_RUNNER
+npm run test:gemini       # usa a API do Gemini
+npm run test:claude-code  # usa o Claude Agent SDK
+```
+
+## Outros comandos
+
+```bash
+npm run lint
+npm run format
+```
+
+## Licença
+
+[MIT](LICENSE)

package/dist/env.js

@@ -0,0 +1,19 @@
+import "dotenv/config";
+import { z } from "zod";
+const envSchema = z.object({
+    TRANSPORT_TYPE: z.enum(["stdio", "httpStream"]).default("stdio"),
+    PORT: z.preprocess((val) => (val === undefined ? undefined : Number(val)), z.number().int().default(3000)),
+    IBGE_API_AGREGADOS: z
+        .url()
+        .default("https://servicodados.ibge.gov.br/api/v3/agregados"),
+    IBGE_API_LOCALIDADES: z
+        .url()
+        .default("https://servicodados.ibge.gov.br/api/v1/localidades"),
+});
+const envParse = envSchema.safeParse(process.env);
+if (!envParse.success) {
+    console.error("Invalid environment variables:", envParse.error.issues);
+    process.exit(1);
+}
+const env = envParse.data;
+export default env;

package/dist/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer } from "node:http";
+import env from "./env.js";
+import * as registerTool from "./tools/index.js";
+import version from "./version.js";
+const server = new McpServer({
+    name: "IBGE MCP Server",
+    version,
+});
+const tools = Object.values(registerTool);
+for (const tool of tools) {
+    tool(server);
+}
+if (env.TRANSPORT_TYPE === "httpStream") {
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+    });
+    await server.connect(transport);
+    const httpServer = createServer((req, res) => {
+        transport.handleRequest(req, res);
+    });
+    httpServer.listen(env.PORT, () => {
+        console.log(`IBGE MCP Server listening on http://localhost:${env.PORT}`);
+    });
+}
+else {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/tools/agregado-dados.js

@@ -0,0 +1,56 @@
+import axios from "axios";
+import { z } from "zod";
+import env from "../env.js";
+export function registerAgregadoDadosTool(server) {
+    server.registerTool("agregado-dados", {
+        description: "Busca os dados de um agregado no IBGE",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            agregadoId: z
+                .string()
+                .describe("Id do agregado, obtido pela ferramenta 'agregados'. Ex.: '6579'."),
+            periodo: z
+                .string()
+                .describe("Período dos dados. Um ano (ex.: '2018'), vários separados por '|' " +
+                "(ex.: '2017|2018'), um intervalo (ex.: '2017-2019') ou os últimos N " +
+                "períodos com número negativo (ex.: '-6'). Use os períodos válidos " +
+                "informados em 'agregado-metadados'."),
+            variavelId: z
+                .string()
+                .describe("Id da variável, obtido em 'agregado-metadados'. Ex.: '9324'." +
+                "Várias variáveis podem ser separadas por '|'."),
+            localidades: z
+                .string()
+                .describe("Localidades no formato 'N<nivel>[<id>]', combinando o código do " +
+                "nível territorial (de 'agregado-metadados', ex.: N6 = município, " +
+                "N3 = estado, N1 = Brasil) com o id da localidade (da ferramenta " +
+                "'localidades'). Ex.: 'N6[3550308]' para o município de São Paulo, " +
+                "'N3[35]' para o estado de São Paulo. Vários ids: 'N6[3550308,3304557]'; " +
+                "todos do nível: 'N3[all]'."),
+            classificacao: z
+                .string()
+                .optional()
+                .describe("Filtro opcional de classificações no formato " +
+                "'<classificacaoId>[<categoriaId>,...]', conforme as classificações " +
+                "listadas em 'agregado-metadados'. Ex.: '2[4,5]'."),
+        },
+    }, async ({ agregadoId, periodo, variavelId, localidades, classificacao }) => {
+        let url = `${env.IBGE_API_AGREGADOS}/${agregadoId}/periodos/${periodo}/variaveis/${variavelId}?localidades=${encodeURIComponent(localidades)}`;
+        if (classificacao) {
+            url += `&classificacao=${encodeURIComponent(classificacao)}`;
+        }
+        const response = await axios.get(url);
+        const dados = {
+            fonteUrl: url,
+            dados: response.data,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(dados, null, 2) }],
+        };
+    });
+}

package/dist/tools/agregado-metadados.js

@@ -0,0 +1,42 @@
+import axios from "axios";
+import { z } from "zod";
+import env from "../env.js";
+export function registerAgregadoMetadadosTool(server) {
+    server.registerTool("agregado-metadados", {
+        description: "Busca metadados (variáveis, nivelTerritorial, periodicidade, etc.) de um agregado por agregadoId",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            agregadoId: z
+                .string()
+                .describe("Id do agregado, obtido pela ferramenta 'agregados'. Ex.: '6579'."),
+        },
+    }, async ({ agregadoId }) => {
+        const response = await axios.get(`${env.IBGE_API_AGREGADOS}/${agregadoId}/metadados`);
+        const data = response.data;
+        const agregadoMetadados = {
+            agregadoId: data.id,
+            nome: data.nome,
+            pesquisa: data.pesquisa,
+            assunto: data.assunto,
+            periodicidade: data.periodicidade,
+            nivelTerritorial: data.nivelTerritorial,
+            variaveis: data.variaveis.map((variavel) => ({
+                variavelId: variavel.id,
+                nome: variavel.nome,
+                unidade: variavel.unidade,
+                sumarizacao: variavel.sumarizacao,
+            })),
+            classificacoes: data.classificacoes,
+        };
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(agregadoMetadados, null, 2) },
+            ],
+        };
+    });
+}

package/dist/tools/agregados.js

@@ -0,0 +1,39 @@
+import axios from "axios";
+import { z } from "zod";
+import env from "../env.js";
+export function registerAgregadosTool(server) {
+    server.registerTool("agregados", {
+        description: "Busca agregados de uma pesquisa por pesquisaId do IBGE",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            pesquisaId: z
+                .string()
+                .describe("Id da pesquisa, obtido pela ferramenta 'pesquisas'. Ex.: 'CD'."),
+        },
+    }, async ({ pesquisaId }) => {
+        const response = await axios.get(env.IBGE_API_AGREGADOS);
+        const pesquisa = response.data.filter((pesquisa) => pesquisa.id === pesquisaId)[0];
+        if (!pesquisa) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Pesquisa com id ${pesquisaId} não encontrada.`,
+                    },
+                ],
+            };
+        }
+        const agregados = pesquisa.agregados.map((agregado) => ({
+            agregadoId: agregado.id,
+            nome: agregado.nome,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(agregados, null, 2) }],
+        };
+    });
+}

package/dist/tools/data-hora.js

@@ -0,0 +1,61 @@
+/** Os dados do IBGE são publicados em referência ao horário de Brasília. */
+const FUSO_HORARIO = "America/Sao_Paulo";
+const formatter = new Intl.DateTimeFormat("en-CA", {
+    timeZone: FUSO_HORARIO,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    // h23 e não hour12:false, que em alguns locales devolve '24' à meia-noite.
+    hourCycle: "h23",
+    timeZoneName: "longOffset",
+});
+/**
+ * Quebra o instante nos campos do fuso de Brasília. `Date` só sabe formatar em
+ * UTC ou no fuso da máquina, então o `Intl` é quem faz a conversão — assim o
+ * resultado não muda conforme o servidor onde isto roda.
+ */
+function descreverInstante(agora) {
+    const partes = new Map(formatter
+        .formatToParts(agora)
+        .map((parte) => [parte.type, parte.value]));
+    const campo = (nome) => partes.get(nome) ?? "";
+    // 'GMT-03:00' -> '-03:00'; no horário de Greenwich o Intl devolve só 'GMT'.
+    const offset = campo("timeZoneName").replace("GMT", "") || "+00:00";
+    const data = `${campo("year")}-${campo("month")}-${campo("day")}`;
+    const hora = `${campo("hour")}:${campo("minute")}:${campo("second")}`;
+    return {
+        dataHora: `${data}T${hora}${offset}`,
+        data,
+        hora,
+        ano: Number(campo("year")),
+        mes: Number(campo("month")),
+        dia: Number(campo("day")),
+        fusoHorario: FUSO_HORARIO,
+        dataHoraUtc: agora.toISOString(),
+    };
+}
+export function registerDataHoraTool(server) {
+    server.registerTool("data-hora", {
+        description: "Retorna a data e a hora atuais no fuso de Brasília (America/Sao_Paulo). " +
+            "Use antes de responder qualquer pergunta relativa ao momento presente — " +
+            "'hoje', 'ano passado', 'atualmente', 'último ano disponível' — para saber " +
+            "a que ano o usuário se refere, em vez de supor. " +
+            "Atenção: o ano atual não é necessariamente o último período publicado de " +
+            "uma pesquisa; para isso consulte os períodos do agregado.",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            // O valor muda a cada chamada.
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async () => {
+        const resultado = descreverInstante(new Date());
+        return {
+            content: [{ type: "text", text: JSON.stringify(resultado, null, 2) }],
+        };
+    });
+}

package/dist/tools/index.js

@@ -0,0 +1,6 @@
+export { registerPesquisasTool } from "./pesquisas.js";
+export { registerAgregadosTool } from "./agregados.js";
+export { registerAgregadoMetadadosTool } from "./agregado-metadados.js";
+export { registerAgregadoDadosTool } from "./agregado-dados.js";
+export { registerLocalidadesTool } from "./localidades.js";
+export { registerDataHoraTool } from "./data-hora.js";

package/dist/tools/localidades.js

@@ -0,0 +1,87 @@
+import axios from "axios";
+import { z } from "zod";
+import env from "../env.js";
+const normalize = (value) => value.normalize("NFD").replace(/[̀-ͯ]/g, "").trim().toLowerCase();
+const matchEstado = (estado, busca) => {
+    const buscaNormalizada = normalize(busca);
+    return (normalize(estado.sigla) === buscaNormalizada ||
+        normalize(estado.nome) === buscaNormalizada);
+};
+export function registerLocalidadesTool(server) {
+    server.registerTool("localidades", {
+        description: "Descobre o id de localidade do IBGE de um estado ou cidade. " +
+            "Use 'estado' para buscar um estado por nome ou sigla (ex.: 'São Paulo' ou 'SP'). " +
+            "Para buscar uma cidade, use 'cidade' como objeto { estado, nome } para evitar ambiguidade, " +
+            "pois existem cidades com o mesmo nome em estados diferentes. " +
+            "É possível buscar estado e cidade na mesma chamada.",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            estado: z
+                .string()
+                .optional()
+                .describe("Nome ou sigla do estado, ex.: 'São Paulo' ou 'SP'"),
+            cidade: z
+                .object({
+                estado: z
+                    .string()
+                    .describe("Nome ou sigla do estado da cidade, ex.: 'SP'"),
+                nome: z.string().describe("Nome da cidade, ex.: 'Campinas'"),
+            })
+                .optional()
+                .describe("Cidade a ser buscada, com o estado para desambiguar o nome"),
+        },
+    }, async ({ estado, cidade }) => {
+        if (!estado && !cidade) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Informe 'estado' ou 'cidade' para buscar uma localidade.",
+                    },
+                ],
+            };
+        }
+        const resultado = {};
+        if (estado) {
+            const response = await axios.get(`${env.IBGE_API_LOCALIDADES}/estados`);
+            const encontrado = response.data.find((uf) => matchEstado(uf, estado));
+            resultado.estado = encontrado
+                ? {
+                    localidadeId: encontrado.id,
+                    sigla: encontrado.sigla,
+                    nome: encontrado.nome,
+                    regiao: encontrado.regiao.nome,
+                }
+                : `Estado '${estado}' não encontrado.`;
+        }
+        if (cidade) {
+            const response = await axios.get(`${env.IBGE_API_LOCALIDADES}/municipios`);
+            const nomeNormalizado = normalize(cidade.nome);
+            const encontrados = response.data.filter((municipio) => normalize(municipio.nome) === nomeNormalizado &&
+                matchEstado(municipio.microrregiao.mesorregiao.UF, cidade.estado));
+            resultado.cidade =
+                encontrados.length > 0
+                    ? encontrados.map((municipio) => {
+                        const uf = municipio.microrregiao.mesorregiao.UF;
+                        return {
+                            localidadeId: municipio.id,
+                            nome: municipio.nome,
+                            estado: {
+                                localidadeId: uf.id,
+                                sigla: uf.sigla,
+                                nome: uf.nome,
+                            },
+                        };
+                    })
+                    : `Cidade '${cidade.nome}' não encontrada no estado '${cidade.estado}'.`;
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(resultado, null, 2) }],
+        };
+    });
+}

package/dist/tools/pesquisas.js

@@ -0,0 +1,22 @@
+import axios from "axios";
+import env from "../env.js";
+export function registerPesquisasTool(server) {
+    server.registerTool("pesquisas", {
+        description: "Busca pesquisas do IBGE",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async () => {
+        const response = await axios.get(env.IBGE_API_AGREGADOS);
+        const pesquisas = response.data.map((pesquisa) => ({
+            pesquisaId: pesquisa.id,
+            nome: pesquisa.nome,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(pesquisas, null, 2) }],
+        };
+    });
+}

package/dist/types/agregado.js

@@ -0,0 +1 @@
+export {};

package/dist/types/localidade.js

@@ -0,0 +1 @@
+export {};

package/dist/version.js

@@ -0,0 +1,4 @@
+import { createRequire } from "node:module";
+// resolves to the package version from package.json
+const { version } = createRequire(import.meta.url)("../package.json");
+export default version;

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "ibge-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for Brazilian IBGE public APIs",
+  "type": "module",
+  "license": "MIT",
+  "author": "Vinicius Cestari",
+  "homepage": "https://github.com/ViniciusCestarii/ibge-mcp-server#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ViniciusCestarii/ibge-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ViniciusCestarii/ibge-mcp-server/issues"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "modelcontextprotocol",
+    "ibge",
+    "brasil",
+    "brazil"
+  ],
+  "main": "./dist/index.js",
+  "bin": {
+    "ibge-mcp-server": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && tsc-alias",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "inspect": "npx @modelcontextprotocol/inspector@0.22.0 tsx src/index.ts",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write src/",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "test:gemini": "TEST_RUNNER=gemini npm test",
+    "test:claude-code": "TEST_RUNNER=claude-code npm test"
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.258",
+    "@eslint/js": "10.0.1",
+    "@types/node": "24.3.1",
+    "eslint": "10.1.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-prettier": "5.5.5",
+    "prettier": "3.8.1",
+    "tsc-alias": "1.9.4",
+    "tsx": "4.20.5",
+    "typescript": "5.9.2",
+    "typescript-eslint": "8.57.2"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "axios": "1.11.0",
+    "dotenv": "17.3.1",
+    "zod": "4.3.6"
+  }
+}