bcb_serie_valores

Retrieve historical economic data from the Brazilian Central Bank's time series database. Query indicators like IPCA, Selic, and exchange rates by code with optional date filters.

Instructions

Consulta valores de uma série temporal do BCB por código. Retorna dados históricos com data e valor.

Input Schema

TableJSON Schema

Name	Required	Description
`codigo`	Yes	Código da série no SGS/BCB (ex: 433 para IPCA mensal, 11 para Selic)
`dataInicial`	No	Data inicial no formato yyyy-MM-dd ou dd/MM/yyyy (opcional)
`dataFinal`	No	Data final no formato yyyy-MM-dd ou dd/MM/yyyy (opcional)

Implementation Reference

src/tools.ts:351-390 (handler)

The handler function `handleSerieValores` performs the API request to the BCB (Banco Central do Brasil) service, formats the dates, fetches the data, and returns the result.

export async function handleSerieValores(
  args: { codigo: number; dataInicial?: string; dataFinal?: string },
  timeoutMs?: number,
  maxRetries?: number
): Promise<ToolResult> {
  try {
    let url = `${BCB_API_BASE}.${args.codigo}/dados?formato=json`;
    if (args.dataInicial) url += `&dataInicial=${formatDateForApi(args.dataInicial)}`;
    if (args.dataFinal) url += `&dataFinal=${formatDateForApi(args.dataFinal)}`;

    const data = await fetchBcbApi(url, timeoutMs, maxRetries) as SerieValor[];

    if (!Array.isArray(data) || data.length === 0) {
      return {
        content: [{ type: "text" as const, text: `Nenhum dado encontrado para a série ${args.codigo} no período solicitado.` }]
      };
    }

    const serieInfo = SERIES_POPULARES.find(s => s.codigo === args.codigo);
    const result = {
      serie: {
        codigo: args.codigo,
        nome: serieInfo?.nome || `Série ${args.codigo}`,
        categoria: serieInfo?.categoria || "Desconhecida",
        periodicidade: serieInfo?.periodicidade || "Desconhecida"
      },
      totalRegistros: data.length,
      periodoInicial: data[0].data,
      periodoFinal: data[data.length - 1].data,
      dados: data.map(d => ({ data: d.data, valor: parseFloat(d.valor) }))
    };

    return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
  } catch (error) {
    return {
      content: [{ type: "text" as const, text: `Erro ao consultar série ${args.codigo}: ${error instanceof Error ? error.message : String(error)}` }],
      isError: true
    };
  }
}

src/tools.ts:743-754 (schema)

The tool definition for `bcb_serie_valores` includes its name, description, and input schema (requiring a `codigo`, with optional `dataInicial` and `dataFinal`).

{
  name: "bcb_serie_valores",
  description: "Consulta valores de uma série temporal do BCB por código. Retorna dados históricos com data e valor.",
  inputSchema: {
    type: "object" as const,
    properties: {
      codigo: { type: "number" as const, description: "Código da série no SGS/BCB (ex: 433 para IPCA mensal, 11 para Selic)" },
      dataInicial: { type: "string" as const, description: "Data inicial no formato yyyy-MM-dd ou dd/MM/yyyy (opcional)" },
      dataFinal: { type: "string" as const, description: "Data final no formato yyyy-MM-dd ou dd/MM/yyyy (opcional)" }
    },
    required: ["codigo"]
  }

src/tools.ts:846-847 (registration)
The tool `bcb_serie_valores` is registered within the `dispatchTool` switch statement to map the tool name to the handler function.
```
case "bcb_serie_valores":
  return handleSerieValores(args as { codigo: number; dataInicial?: string; dataFinal?: string }, timeoutMs, maxRetries);
```

BCB MCP