Banco Central do Brasil (BCB) — SGS Time Series MCP Server
Official17 toolsLive
by SidneyBissoli · TypeScript
Banco Central do Brasil (BCB): SGS series, Focus expectations, PTAX, stats + provenance. 17 tools.
io.github.SidneyBissoli/bcb-br-mcp (MCP Server)
The Banco Central do Brasil (BCB) SGS Time Series MCP Server provides access to BCB SGS series, focus expectations, and PTAX exchange-rate data, along with statistics plus provenance. It is identified as io.github.SidneyBissoli/bcb-br-mcp and exposes 17 tools for economic and financial datasets.
🛠️ Key Features
BCB SGS time series
Focus expectations
PTAX exchange-rate data
Statistics with provenance
17 tools
🚀 Use Cases
Retrieve Brazilian macroeconomic and financial time series
Use SGS, focus expectations, and PTAX data for analysis workflows
Reference data provenance alongside statistics
⚡ Developer Benefits
Model Context Protocol (MCP) server for economic-data retrieval
Tool-based access (17 tools)
Topics align to inflation, interest-rate, exchange-rate, and related datasets
⚠️ Limitations
Scope is limited to what is listed: SGS series, focus expectations, PTAX, and accompanying statistics/provenance.
Consulta o histórico de valores de UMA série temporal do BCB pelo código SGS, opcionalmente limitado por um intervalo de datas (dataInicial/dataFinal). Quando usar: para obter a série histórica completa ou uma janela de datas específica. Quando NÃO usar: para apenas os pontos mais recentes use bcb_serie_ultimos; para a variação percentual use bcb_variacao; para comparar várias séries use bcb_comparar; se não souber o código, descubra-o antes com bcb_buscar_serie ou bcb_series_populares. Retorna: objeto `serie` (codigo, nome, categoria, periodicidade), `totalRegistros`, `periodoInicial`, `periodoFinal` e `dados` (array de {data, valor}); quando não há dados, `totalRegistros` = 0 e uma `observacao` explicativa. Períodos longos: a API do BCB limita séries DIÁRIAS a 10 anos por consulta e recusa janela aberta (HTTP 406). Isso é tratado automaticamente — a janela é fatiada em requisições de até 3 anos e o resultado vem fundido e ordenado, com `chunking` na resposta dizendo quantas janelas foram usadas; se o período pedido estava aberto numa série diária, `janelaAplicada` diz qual janela foi usada e por quê. Harmonização: `frequencia` (mensal|trimestral|anual) reamostra a série antes de responder, com a convenção escolhida em `agregacao`; a resposta traz `harmonizacao` com `derived: true` e a nota do cálculo. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
Parameters5
codigo
number
required
Código da série no SGS/BCB (ex: 433 para IPCA mensal, 11 para Selic)
dataInicial
string
optional
Data inicial no formato yyyy-MM-dd ou dd/MM/yyyy (opcional)
dataFinal
string
optional
Data final no formato yyyy-MM-dd ou dd/MM/yyyy (opcional)
frequencia
string
optional
Opcional: reamostra a série para esta frequência antes de responder (só agrega para períodos MAIORES; pedir frequência mais fina que a da série é recusado). Útil para comparar séries de periodicidades diferentes.
agregacao
string
optional
Como agregar os valores de cada período quando `frequencia` é informada. `ultimo` (padrão) serve a nível de preço, taxa e índice; `soma` a fluxo; `acumulada` a séries que JÁ SÃO variação percentual (IPCA mensal, por exemplo), compondo geometricamente — somar 12 variações mensais NÃO dá a inflação do ano.
Raw schema
{
"type": "object",
"properties": {
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB (ex: 433 para IPCA mensal, 11 para Selic)"
},
"dataInicial": {
"type": "string",
"description": "Data inicial no formato yyyy-MM-dd ou dd/MM/yyyy (opcional)"
},
"dataFinal": {
"type": "string",
"description": "Data final no formato yyyy-MM-dd ou dd/MM/yyyy (opcional)"
},
"frequencia": {
"type": "string",
"enum": [
"mensal",
"trimestral",
"anual"
],
"description": "Opcional: reamostra a série para esta frequência antes de responder (só agrega para períodos MAIORES; pedir frequência mais fina que a da série é recusado). Útil para comparar séries de periodicidades diferentes."
},
"agregacao": {
"type": "string",
"enum": [
"ultimo",
"primeiro",
"media",
"soma",
"acumulada"
],
"default": "ultimo",
"description": "Como agregar os valores de cada período quando `frequencia` é informada. `ultimo` (padrão) serve a nível de preço, taxa e índice; `soma` a fluxo; `acumulada` a séries que JÁ SÃO variação percentual (IPCA mensal, por exemplo), compondo geometricamente — somar 12 variações mensais NÃO dá a inflação do ano."
}
},
"required": [
"codigo"
],
"additionalProperties": false
}
bcb_serie_ultimos
Obtém as últimas N observações de UMA série temporal do BCB (mais recentes primeiro a partir do fim da série). Quando usar: para ver os dados mais recentes sem precisar calcular datas (ex.: últimos 12 meses do IPCA). Quantidade entre 1 e 1000 (padrão 10). Quando NÃO usar: para um intervalo de datas ou o histórico completo use bcb_serie_valores. Retorna: objeto `serie`, `totalRegistros` e `dados` (array de {data, valor}); sem dados, `totalRegistros` = 0 com `observacao`. Acima de 20: o endpoint nativo do BCB rejeita N > 20 em qualquer periodicidade, então o servidor descobre a periodicidade da série e busca por janela de datas, devolvendo os N últimos pontos. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
Parameters2
codigo
number
required
Código da série no SGS/BCB
quantidade
number
optional
Quantidade de valores a retornar (1-1000, padrão: 10). A API do BCB tem teto de 20 no endpoint nativo; acima disso o servidor busca por janela de datas e devolve os N últimos.
Raw schema
{
"type": "object",
"properties": {
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB"
},
"quantidade": {
"type": "number",
"description": "Quantidade de valores a retornar (1-1000, padrão: 10). A API do BCB tem teto de 20 no endpoint nativo; acima disso o servidor busca por janela de datas e devolve os N últimos.",
"default": 10,
"minimum": 1,
"maximum": 1000
}
},
"required": [
"codigo"
],
"additionalProperties": false
}
bcb_serie_metadados
Obtém a descrição de UMA série do BCB (nome, periodicidade, categoria, fonte e último valor), sem trazer a série histórica. Quando usar: para confirmar o que uma série representa e com que frequência é publicada antes de consultar os dados. Quando NÃO usar: para os valores em si use bcb_serie_valores ou bcb_serie_ultimos. Retorna: codigo, nome, periodicidade, categoria, fonte, `ultimoValor` e URLs diretas da API (urlConsulta, urlUltimos10). Limite da fonte: a API do SGS NÃO publica endpoint de metadados por série — não há unidade de medida disponível. Nome e categoria vêm do catálogo curado do servidor (135 séries verificadas contra a origem) e, fora dele, a periodicidade é inferida do espaçamento das observações, sinalizada por `periodicidadeInferida`. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
Parameters1
codigo
number
required
Código da série no SGS/BCB
Raw schema
{
"type": "object",
"properties": {
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB"
}
},
"required": [
"codigo"
],
"additionalProperties": false
}
bcb_series_populares
Lista o catálogo interno curado de 135 séries econômicas do BCB com seus códigos, agrupadas por categoria (Juros, Inflação, Câmbio, Atividade Econômica, Emprego, Fiscal, Setor Externo, Crédito, Agregados Monetários, Poupança); aceita filtro por categoria. Quando usar: para navegar/descobrir as séries disponíveis por tema. Quando NÃO usar: para busca por palavra-chave use bcb_buscar_serie; esta ferramenta não busca valores. Retorna: `totalSeries`, `categorias` (nº de categorias) e `series` — objeto agrupado por categoria quando sem filtro, ou array plano quando filtrado por categoria; cada item tem codigo, nome, categoria, periodicidade e `fonteNome`. Catálogo local: não faz chamada de rede. Procedência: `fonteNome` = 'portal' quando o nome é transcrito do dataset da série no Portal de Dados Abertos do BCB (82 séries, com `unidade`), e 'medido' quando a série não tem dataset lá — nesse caso o nome é herdado e o que foi verificado contra a origem é a periodicidade e a ordem de grandeza. Expectativas do Focus NÃO estão aqui: use bcb_focus_expectativas.
Parameters1
categoria
string
optional
Filtrar por categoria: Juros, Inflação, Câmbio, Atividade Econômica, Emprego, Fiscal, Setor Externo, Crédito, Agregados Monetários, Poupança, Índices de Mercado, Expectativas
Busca séries do BCB por palavra-chave (ou pelo código) em DUAS camadas: o catálogo curado local de 135 séries verificadas contra a origem, que vem primeiro e com `fonteNome` dizendo se o nome é transcrito do portal do BCB ou herdado, e o índice do Portal de Dados Abertos do BCB, com milhares de séries identificadas por código. Ignora acentos e maiúsculas ('inflacao' encontra 'Inflação'); vários termos são combinados com E ('ipca servicos'). Quando usar: para descobrir o código de uma série antes de consultar valores. Quando NÃO usar: para navegar tudo por categoria use bcb_series_populares; para valores use bcb_serie_valores. Retorna: `termo`, `totalEncontradas`, `series` (cada item com codigo, nome, origem — 'curado' ou 'indice' — e, no índice, `dataset` com a página do portal), `catalogo` (origem, obtidoEm, seriesIndexadas, cobertura) e, quando aplicável, `observacao`, `avisos`, `mensagem` e `sugestao`. Cobertura: o índice NÃO é o SGS inteiro, portanto não encontrar aqui não prova que a série não exista — o campo `catalogo.cobertura` diz isso explicitamente em toda resposta. Comportamento de rede: o índice é servido de cache com validade de 24 h e a renovação é feita pela primeira busca após o vencimento (uma requisição ao portal, ~1 s); as demais buscas não tocam a rede. Se o portal estiver fora, a busca degrada para o catálogo curado (ou para o último índice obtido) e sinaliza em `avisos`, sempre com a data de obtenção visível.
Parameters2
termo
string
required
Termo de busca (mínimo 2 caracteres) ou o código da série. Vários termos são combinados com E, sem distinção de acento; a palavra de todo dia é traduzida para a do BCB (déficit→resultado primário, calote→inadimplência, desemprego→desocupação) e a resposta diz quando isso aconteceu (notasVocabulario).
limite
number
optional
Máximo de séries a devolver (1-100, padrão: 20). `totalEncontradas` traz o total antes do corte.
Raw schema
{
"type": "object",
"properties": {
"termo": {
"type": "string",
"description": "Termo de busca (mínimo 2 caracteres) ou o código da série. Vários termos são combinados com E, sem distinção de acento; a palavra de todo dia é traduzida para a do BCB (déficit→resultado primário, calote→inadimplência, desemprego→desocupação) e a resposta diz quando isso aconteceu (notasVocabulario).",
"minLength": 2
},
"limite": {
"type": "number",
"description": "Máximo de séries a devolver (1-100, padrão: 20). `totalEncontradas` traz o total antes do corte.",
"default": 20,
"minimum": 1,
"maximum": 100
}
},
"required": [
"termo"
],
"additionalProperties": false
}
bcb_indicadores_atuais
Atalho que retorna, em uma única chamada, o valor mais recente dos principais indicadores da economia brasileira: Selic (meta do Copom), IPCA mensal, IPCA acumulado 12 meses, dólar comercial de venda (série diária) e IBC-Br. Não recebe parâmetros. Quando usar: para um panorama econômico rápido. Quando NÃO usar: para qualquer outra série, para dados históricos ou para escolher o período use bcb_serie_ultimos ou bcb_serie_valores. Retorna: `consultadoEm` (timestamp ISO 8601) e `indicadores` (array com indicador, codigo, data, valor — ou `erro` no item). Resiliente: cada indicador é buscado de forma independente, então a falha de um não derruba os demais. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
Calcula a variação percentual de UMA série no período, mais estatísticas descritivas. Para série de NÍVEL (dólar, Selic, dívida, produção) é a variação entre o primeiro e o último ponto; para série que JÁ É uma variação por período (IPCA 433, INPC 188, IGP-M 189 e demais índices de preço mensais do catálogo; Selic/CDI acumulados no mês 4390/4391; rentabilidade da poupança 25/195) é o ACUMULADO do período por encadeamento — "quanto o IPCA acumulou em 2024" ou "quanto a Selic rendeu em 2024" é esta tool. O campo `analise.metodo` diz qual das duas contas foi feita; código fora do catálogo curado é tratado como nível. Série de acumulado móvel (IPCA em 12 meses, 13522) é recusada com orientação — o valor publicado já é a resposta. O período pode ser definido por datas (dataInicial/dataFinal) OU pelos últimos N períodos (parâmetro `periodos`, que tem precedência e ignora as datas). Quando usar: para medir tendência/variação/acumulado de uma única série. Quando NÃO usar: para comparar várias séries use bcb_comparar; para os valores brutos use bcb_serie_valores. Requer ao menos 2 observações no período (senão retorna `isError`). Retorna: `serie`, `periodo` (dataInicial, dataFinal, totalPeriodos), `analise` (metodo, valorInicial, valorFinal, diferencaAbsoluta — nula quando encadeado —, variacaoPercentual, variacaoFormatada) e `estatisticas` (maximo, minimo, media, amplitude). Períodos longos são tratados automaticamente: janela diária acima de 10 anos é fatiada (a API do BCB responde 406) e `periodos` acima de 20 é atendido por janela de datas; `chunking` e `janelaAplicada` aparecem na resposta quando isso acontece. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
Parameters4
codigo
number
required
Código da série no SGS/BCB
dataInicial
string
optional
Data inicial (yyyy-MM-dd ou dd/MM/yyyy). Se não informada, usa o primeiro valor disponível.
dataFinal
string
optional
Data final (yyyy-MM-dd ou dd/MM/yyyy). Se não informada, usa o último valor disponível.
periodos
number
optional
Alternativa: calcular variação dos últimos N períodos (ignora datas se informado). Acima de 20 o servidor busca por janela de datas, porque o endpoint nativo do BCB tem esse teto.
Raw schema
{
"type": "object",
"properties": {
"codigo": {
"type": "number",
"description": "Código da série no SGS/BCB"
},
"dataInicial": {
"type": "string",
"description": "Data inicial (yyyy-MM-dd ou dd/MM/yyyy). Se não informada, usa o primeiro valor disponível."
},
"dataFinal": {
"type": "string",
"description": "Data final (yyyy-MM-dd ou dd/MM/yyyy). Se não informada, usa o último valor disponível."
},
"periodos": {
"type": "number",
"description": "Alternativa: calcular variação dos últimos N períodos (ignora datas se informado). Acima de 20 o servidor busca por janela de datas, porque o endpoint nativo do BCB tem esse teto."
}
},
"required": [
"codigo"
],
"additionalProperties": false
}
bcb_comparar
Compara de 2 a 5 séries temporais no MESMO período (dataInicial e dataFinal obrigatórias), calculando a variação percentual de cada uma e ordenando-as num ranking (maior para menor variação). Série de nível entra pela variação entre as pontas; série que já é variação por período (IPCA, INPC, IGP-M mensais do catálogo; Selic/CDI acumulados no mês; poupança) entra pelo ACUMULADO encadeado do período — cada item diz em `metodo` qual conta foi feita, então "qual índice de preço subiu mais em 2024" é esta tool. Quando usar: para comparar/correlacionar a evolução de vários indicadores lado a lado. Quando NÃO usar: para uma única série use bcb_variacao. Retorna: `periodo`, `totalSeries`, `seriesComDados`, `seriesComErro`, `ranking` (cada item com posicao, codigo, nome, metodo, valorInicial, valorFinal, variacaoPercentual, maximo, minimo, media) e `erros`. Resiliente: séries sem dados no período, e séries de acumulado móvel (IPCA em 12 meses), são isoladas em `erros` sem invalidar a comparação. Periodicidades diferentes: comparar uma série diária com uma mensal alinha pontos que não são comparáveis, e a resposta avisa isso em `aviso`; informe `frequencia` (mensal|trimestral|anual) para harmonizar todas na mesma grade antes de comparar, escolhendo a convenção em `agregacao`. Janelas longas em séries diárias são fatiadas automaticamente (limite de 10 anos da API do BCB). Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
Parameters5
codigos
array
required
Array com 2 a 5 códigos de séries para comparar
dataInicial
string
required
Data inicial (yyyy-MM-dd ou dd/MM/yyyy)
dataFinal
string
required
Data final (yyyy-MM-dd ou dd/MM/yyyy)
frequencia
string
optional
Opcional: reamostra a série para esta frequência antes de responder (só agrega para períodos MAIORES; pedir frequência mais fina que a da série é recusado). Útil para comparar séries de periodicidades diferentes.
agregacao
string
optional
Como agregar os valores de cada período quando `frequencia` é informada. `ultimo` (padrão) serve a nível de preço, taxa e índice; `soma` a fluxo; `acumulada` a séries que JÁ SÃO variação percentual (IPCA mensal, por exemplo), compondo geometricamente — somar 12 variações mensais NÃO dá a inflação do ano.
Raw schema
{
"type": "object",
"properties": {
"codigos": {
"type": "array",
"items": {
"type": "number"
},
"description": "Array com 2 a 5 códigos de séries para comparar",
"minItems": 2,
"maxItems": 5
},
"dataInicial": {
"type": "string",
"description": "Data inicial (yyyy-MM-dd ou dd/MM/yyyy)"
},
"dataFinal": {
"type": "string",
"description": "Data final (yyyy-MM-dd ou dd/MM/yyyy)"
},
"frequencia": {
"type": "string",
"enum": [
"mensal",
"trimestral",
"anual"
],
"description": "Opcional: reamostra a série para esta frequência antes de responder (só agrega para períodos MAIORES; pedir frequência mais fina que a da série é recusado). Útil para comparar séries de periodicidades diferentes."
},
"agregacao": {
"type": "string",
"enum": [
"ultimo",
"primeiro",
"media",
"soma",
"acumulada"
],
"default": "ultimo",
"description": "Como agregar os valores de cada período quando `frequencia` é informada. `ultimo` (padrão) serve a nível de preço, taxa e índice; `soma` a fluxo; `acumulada` a séries que JÁ SÃO variação percentual (IPCA mensal, por exemplo), compondo geometricamente — somar 12 variações mensais NÃO dá a inflação do ano."
}
},
"required": [
"codigos",
"dataInicial",
"dataFinal"
],
"additionalProperties": false
}
bcb_correlacao
Calcula a correlação estatística entre 2 a 5 séries temporais do BCB no MESMO período (dataInicial e dataFinal obrigatórias), par a par. Quando usar: para medir se dois indicadores se movem juntos (ex.: dólar e Selic, IPCA e IGP-M). Quando NÃO usar: para comparar a variação de cada série lado a lado use bcb_comparar; para uma série só use bcb_variacao. Métodos: `pearson` (padrão) mede relação LINEAR entre os valores; `spearman` mede relação MONÓTONA entre os postos e é o adequado quando a relação não é reta ou quando uma série fica parada em platôs (taxa de juros entre reuniões do Copom). Base: `nivel` (padrão) correlaciona os valores; `variacao` correlaciona a mudança percentual de um ponto para o outro — prefira `variacao` quando as duas séries têm tendência (preço, índice, estoque), porque o nível de duas séries crescentes tem correlação alta só porque ambas crescem com o tempo. Retorna: `periodo`, `metodo`, `base`, `series`, `alinhamento` (datas cruzadas, completas e parciais), `pares` (cada um com codigoA/codigoB, `coeficiente` entre -1 e 1, `n`, `descartados` e `interpretacao` em prosa), `erros` e `derivacao`. Coeficiente que não pode ser calculado vem `null` com `motivo` — nunca 0, que significaria ausência medida de relação. Periodicidades diferentes são RECUSADAS, não avisadas: cruzar uma série diária com uma mensal por data casa só as datas coincidentes (cerca de 7 por ano) e produziria um coeficiente sobre esse punhado; informe `frequencia` para harmonizar todas na mesma grade antes de correlacionar. Correlação não estabelece causalidade. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
Parameters7
codigos
array
required
Array com 2 a 5 códigos de séries para correlacionar par a par
dataInicial
string
required
Data inicial (yyyy-MM-dd ou dd/MM/yyyy)
dataFinal
string
required
Data final (yyyy-MM-dd ou dd/MM/yyyy)
metodo
string
optional
`pearson` mede relação linear entre os valores; `spearman` mede relação monótona entre os postos (com posto médio nos empates) e é o adequado quando a relação não é reta ou quando uma das séries fica parada em platôs, como a Selic entre reuniões do Copom.
base
string
optional
`nivel` correlaciona os valores; `variacao` correlaciona a mudança percentual de um ponto para o seguinte. Prefira `variacao` quando as duas séries têm tendência: o nível de duas séries crescentes tem correlação alta só porque ambas crescem com o tempo.
frequencia
string
optional
Opcional: reamostra a série para esta frequência antes de responder (só agrega para períodos MAIORES; pedir frequência mais fina que a da série é recusado). Útil para comparar séries de periodicidades diferentes.
agregacao
string
optional
Como agregar os valores de cada período quando `frequencia` é informada. `ultimo` (padrão) serve a nível de preço, taxa e índice; `soma` a fluxo; `acumulada` a séries que JÁ SÃO variação percentual (IPCA mensal, por exemplo), compondo geometricamente — somar 12 variações mensais NÃO dá a inflação do ano.
Raw schema
{
"type": "object",
"properties": {
"codigos": {
"type": "array",
"items": {
"type": "number"
},
"description": "Array com 2 a 5 códigos de séries para correlacionar par a par",
"minItems": 2,
"maxItems": 5
},
"dataInicial": {
"type": "string",
"description": "Data inicial (yyyy-MM-dd ou dd/MM/yyyy)"
},
"dataFinal": {
"type": "string",
"description": "Data final (yyyy-MM-dd ou dd/MM/yyyy)"
},
"metodo": {
"type": "string",
"enum": [
"pearson",
"spearman"
],
"default": "pearson",
"description": "`pearson` mede relação linear entre os valores; `spearman` mede relação monótona entre os postos (com posto médio nos empates) e é o adequado quando a relação não é reta ou quando uma das séries fica parada em platôs, como a Selic entre reuniões do Copom."
},
"base": {
"type": "string",
"enum": [
"nivel",
"variacao"
],
"default": "nivel",
"description": "`nivel` correlaciona os valores; `variacao` correlaciona a mudança percentual de um ponto para o seguinte. Prefira `variacao` quando as duas séries têm tendência: o nível de duas séries crescentes tem correlação alta só porque ambas crescem com o tempo."
},
"frequencia": {
"type": "string",
"enum": [
"mensal",
"trimestral",
"anual"
],
"description": "Opcional: reamostra a série para esta frequência antes de responder (só agrega para períodos MAIORES; pedir frequência mais fina que a da série é recusado). Útil para comparar séries de periodicidades diferentes."
},
"agregacao": {
"type": "string",
"enum": [
"ultimo",
"primeiro",
"media",
"soma",
"acumulada"
],
"default": "ultimo",
"description": "Como agregar os valores de cada período quando `frequencia` é informada. `ultimo` (padrão) serve a nível de preço, taxa e índice; `soma` a fluxo; `acumulada` a séries que JÁ SÃO variação percentual (IPCA mensal, por exemplo), compondo geometricamente — somar 12 variações mensais NÃO dá a inflação do ano."
}
},
"required": [
"codigos",
"dataInicial",
"dataFinal"
],
"additionalProperties": false
}
bcb_deflacionar
Converte uma série NOMINAL do BCB em valores REAIS (moeda constante), descontando a inflação do período — a diferença entre 'o salário mínimo subiu 46% desde 2020' e 'o salário mínimo subiu 5% em poder de compra'. Quando usar: sempre que valores em reais de épocas diferentes forem comparados. Quando NÃO usar: para séries que já são percentuais, índices ou taxas (deflacionar uma taxa de juros não significa nada); para a série nominal crua use bcb_serie_valores. Índice: `ipca` (padrão), `inpc` ou `igpm`. Base: `mesBase` no formato yyyy-MM define em reais de que mês os valores são expressos; sem ele, usa o último mês publicado do índice ('em reais de hoje'). Retorna: `serie`, `deflator` (índice, código, cobertura), `base`, `periodo`, `dados` (cada ponto com valorNominal, `valorReal` e `fator`), `variacao` (a percentual nominal ao lado da real no mesmo período), `derivacao` e `avisos`. Limite da fonte: o SGS não publica número-índice, então o índice é reconstruído compondo as variações mensais — reconstrução conferida contra a própria fonte (diferença máxima de 0,0052 ponto percentual contra o acumulado oficial em 12 meses). Observação fora da cobertura do índice recebe `valorReal: null`, nunca um valor inventado; como o índice sai com defasagem, o mês corrente costuma cair nesse caso. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna `isError: true` com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em `structuredContent` (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
Parameters7
codigo
number
required
Código da série NOMINAL a deflacionar (ex.: 1619 para salário mínimo)
dataInicial
string
required
Data inicial (yyyy-MM-dd ou dd/MM/yyyy)
dataFinal
string
required
Data final (yyyy-MM-dd ou dd/MM/yyyy)
indice
string
optional
Índice de preços usado como deflator: IPCA (433), INPC (188) ou IGP-M (189)
mesBase
string
optional
Mês em cujos preços os valores serão expressos, no formato yyyy-MM. Sem ele, usa o último mês publicado do índice — isto é, 'em reais de hoje'.
frequencia
string
optional
Opcional: reamostra a série para esta frequência antes de responder (só agrega para períodos MAIORES; pedir frequência mais fina que a da série é recusado). Útil para comparar séries de periodicidades diferentes.
agregacao
string
optional
Como agregar os valores de cada período quando `frequencia` é informada. `ultimo` (padrão) serve a nível de preço, taxa e índice; `soma` a fluxo; `acumulada` a séries que JÁ SÃO variação percentual (IPCA mensal, por exemplo), compondo geometricamente — somar 12 variações mensais NÃO dá a inflação do ano.
Raw schema
{
"type": "object",
"properties": {
"codigo": {
"type": "number",
"description": "Código da série NOMINAL a deflacionar (ex.: 1619 para salário mínimo)"
},
"dataInicial": {
"type": "string",
"description": "Data inicial (yyyy-MM-dd ou dd/MM/yyyy)"
},
"dataFinal": {
"type": "string",
"description": "Data final (yyyy-MM-dd ou dd/MM/yyyy)"
},
"indice": {
"type": "string",
"enum": [
"ipca",
"inpc",
"igpm"
],
"default": "ipca",
"description": "Índice de preços usado como deflator: IPCA (433), INPC (188) ou IGP-M (189)"
},
"mesBase": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}$",
"description": "Mês em cujos preços os valores serão expressos, no formato yyyy-MM. Sem ele, usa o último mês publicado do índice — isto é, 'em reais de hoje'."
},
"frequencia": {
"type": "string",
"enum": [
"mensal",
"trimestral",
"anual"
],
"description": "Opcional: reamostra a série para esta frequência antes de responder (só agrega para períodos MAIORES; pedir frequência mais fina que a da série é recusado). Útil para comparar séries de periodicidades diferentes."
},
"agregacao": {
"type": "string",
"enum": [
"ultimo",
"primeiro",
"media",
"soma",
"acumulada"
],
"default": "ultimo",
"description": "Como agregar os valores de cada período quando `frequencia` é informada. `ultimo` (padrão) serve a nível de preço, taxa e índice; `soma` a fluxo; `acumulada` a séries que JÁ SÃO variação percentual (IPCA mensal, por exemplo), compondo geometricamente — somar 12 variações mensais NÃO dá a inflação do ano."
}
},
"required": [
"codigo",
"dataInicial",
"dataFinal"
],
"additionalProperties": false
}
bcb_focus_expectativas
Consulta as expectativas de mercado do boletim Focus para UM indicador, com o horizonte como parâmetro: mensal, trimestral, anual, inflação nos próximos 12 meses e nos próximos 24 meses. Devolve média, mediana, desvio padrão, mínimo, máximo e número de respondentes por data de coleta. Quando usar: para expectativa de IPCA, IGP-M, PIB, câmbio e afins em um mês, trimestre ou ano específico, ou para a inflação rolante. Quando NÃO usar: para expectativa de Selic por reunião do Copom use bcb_focus_selic; para o valor REALIZADO (não esperado) use bcb_serie_valores. Regras do contrato: `referencia` é obrigatória nos horizontes de calendário (mensal, trimestral, anual) e recusada nos rolantes; `suavizada` só vale nos rolantes; `top5: true` traz as expectativas das cinco instituições mais assertivas e existe nos cinco horizontes. Se não souber o texto exato do indicador ou da referência, chame bcb_focus_referencias primeiro — o conjunto de indicadores MUDA por horizonte, e pedir um indicador no horizonte em que a fonte não o publica é a causa mais comum de resposta vazia. Retorna: `indicador`, `horizonte`, `base` (consenso|top5), `filtro` (referencia, dataInicial, dataFinal, janelaPadrao, suavizada), `totalRegistros`, `expectativas` (array normalizado), `urlConsulta`, `consultadoEm` e, quando aplicável, `observacao`. Sem datas, a janela padrão é de 30 dias. Fonte: Expectativas de Mercado (Focus) do Banco Central do Brasil, via Olinda OData. O Focus é vintage por construção: `coletadoEm` é a data da coleta e `referencia` é o alvo da expectativa — a mesma referência aparece em muitas coletas, e é isso que permite ver a expectativa mudar no tempo. A contagem é feita do nosso lado porque a fonte ignora `$count`; e o filtro é obrigatório por construção porque consulta sem filtro não completa na origem. Microdados por instituição NÃO são expostos: a fonte desativou esse recurso por risco de quebra de confidencialidade.
Parameters8
indicador
string
required
Indicador exatamente como a fonte publica (ex.: 'IPCA', 'IGP-M', 'PIB Total', 'Câmbio'). Veja bcb_focus_referencias.
horizonte
string
required
mensal, trimestral e anual usam `referencia`; inflacao_12m e inflacao_24m são rolantes e não usam
referencia
string
optional
Alvo da expectativa: MM/yyyy (mensal), T/yyyy (trimestral) ou yyyy (anual). Obrigatória nesses três; proibida nos rolantes.
dataInicial
string
optional
Início da janela de COLETA (yyyy-MM-dd ou dd/MM/yyyy). Padrão: 30 dias antes do fim.
dataFinal
string
optional
Fim da janela de COLETA (yyyy-MM-dd ou dd/MM/yyyy). Padrão: hoje.
top5
boolean
optional
Expectativas do Top 5 (as cinco instituições mais assertivas) em vez do consenso; existe nos cinco horizontes
suavizada
boolean
optional
Só nos horizontes rolantes: série suavizada (true) ou não suavizada (false)
limite
number
optional
Máximo de coletas a devolver (1-500, padrão 50)
Raw schema
{
"type": "object",
"properties": {
"indicador": {
"type": "string",
"description": "Indicador exatamente como a fonte publica (ex.: 'IPCA', 'IGP-M', 'PIB Total', 'Câmbio'). Veja bcb_focus_referencias.",
"minLength": 2
},
"horizonte": {
"type": "string",
"enum": [
"mensal",
"trimestral",
"anual",
"inflacao_12m",
"inflacao_24m"
],
"description": "mensal, trimestral e anual usam `referencia`; inflacao_12m e inflacao_24m são rolantes e não usam"
},
"referencia": {
"type": "string",
"description": "Alvo da expectativa: MM/yyyy (mensal), T/yyyy (trimestral) ou yyyy (anual). Obrigatória nesses três; proibida nos rolantes."
},
"dataInicial": {
"type": "string",
"description": "Início da janela de COLETA (yyyy-MM-dd ou dd/MM/yyyy). Padrão: 30 dias antes do fim."
},
"dataFinal": {
"type": "string",
"description": "Fim da janela de COLETA (yyyy-MM-dd ou dd/MM/yyyy). Padrão: hoje."
},
"top5": {
"type": "boolean",
"description": "Expectativas do Top 5 (as cinco instituições mais assertivas) em vez do consenso; existe nos cinco horizontes",
"default": false
},
"suavizada": {
"type": "boolean",
"description": "Só nos horizontes rolantes: série suavizada (true) ou não suavizada (false)"
},
"limite": {
"type": "number",
"description": "Máximo de coletas a devolver (1-500, padrão 50)",
"default": 50,
"minimum": 1,
"maximum": 500
}
},
"required": [
"indicador",
"horizonte"
],
"additionalProperties": false
}
bcb_focus_selic
Consulta as expectativas de mercado do Focus para a taxa Selic, organizadas pela REUNIÃO do Copom (formato R1/2026 = 1ª reunião de 2026). Devolve média, mediana, desvio padrão, mínimo, máximo e número de respondentes por data de coleta. Quando usar: para 'o que o mercado espera da Selic na próxima reunião' ou a trajetória esperada de juros. Quando NÃO usar: para expectativa de Selic média de um ano civil use bcb_focus_expectativas com horizonte anual; para a Selic REALIZADA use bcb_serie_valores (códigos 432, 1178, 4390). É separada de bcb_focus_expectativas porque o eixo temporal é a reunião do Copom, não o calendário. Retorna: `base` (consenso|top5), `filtro`, `totalRegistros`, `expectativas` (com `referencia` = reunião), `urlConsulta`, `consultadoEm` e `observacaoEixo`. Sem datas, a janela padrão é de 30 dias. Fonte: Expectativas de Mercado (Focus) do Banco Central do Brasil, via Olinda OData. O Focus é vintage por construção: `coletadoEm` é a data da coleta e `referencia` é o alvo da expectativa — a mesma referência aparece em muitas coletas, e é isso que permite ver a expectativa mudar no tempo. A contagem é feita do nosso lado porque a fonte ignora `$count`; e o filtro é obrigatório por construção porque consulta sem filtro não completa na origem. Microdados por instituição NÃO são expostos: a fonte desativou esse recurso por risco de quebra de confidencialidade.
Parameters5
reuniao
string
optional
Reunião do Copom no formato R1/2026 (opcional; sem ela, todas as reuniões da janela)
dataInicial
string
optional
Início da janela de COLETA (yyyy-MM-dd ou dd/MM/yyyy). Padrão: 30 dias antes do fim.
dataFinal
string
optional
Fim da janela de COLETA (yyyy-MM-dd ou dd/MM/yyyy). Padrão: hoje.
top5
boolean
optional
Expectativas do Top 5 em vez do consenso
limite
number
optional
Máximo de coletas a devolver (1-500, padrão 50)
Raw schema
{
"type": "object",
"properties": {
"reuniao": {
"type": "string",
"description": "Reunião do Copom no formato R1/2026 (opcional; sem ela, todas as reuniões da janela)"
},
"dataInicial": {
"type": "string",
"description": "Início da janela de COLETA (yyyy-MM-dd ou dd/MM/yyyy). Padrão: 30 dias antes do fim."
},
"dataFinal": {
"type": "string",
"description": "Fim da janela de COLETA (yyyy-MM-dd ou dd/MM/yyyy). Padrão: hoje."
},
"top5": {
"type": "boolean",
"description": "Expectativas do Top 5 em vez do consenso",
"default": false
},
"limite": {
"type": "number",
"description": "Máximo de coletas a devolver (1-500, padrão 50)",
"default": 50,
"minimum": 1,
"maximum": 500
}
},
"additionalProperties": false
}
bcb_focus_referencias
Lista, POR ESCOPO, os indicadores e as referências que o Focus efetivamente publica, para você usar o texto EXATO em bcb_focus_expectativas e em bcb_focus_selic. Escopo = os cinco horizontes de bcb_focus_expectativas mais 'selic', que não é horizonte: o eixo dela é a reunião do Copom, e quem a consome é bcb_focus_selic. Cada bloco diz em `tool` quem o consome. Quando usar: antes da primeira consulta ao Focus, ou quando uma consulta volta vazia — a causa mais comum não é o dado faltar, é o indicador não existir NAQUELE escopo (a fonte publica 9 indicadores no mensal e 26 no anual: 'PIB Total', por exemplo, não existe no mensal) ou a referência estar num formato diferente do publicado. Quando NÃO usar: para os valores das expectativas em si. Sem `escopo`, consulta os seis e devolve tudo; com `escopo`, consulta só aquele. Retorna: `escopos` (para cada um: `tool` que o consome, `formatoReferencia`, `exigeReferencia`, `temTop5`, `indicadores`, `referencias`, `urlConsulta` e `disponivel`), mais `indicadores` e `referencias` como união de todos, `janela`, `totalRegistros` e `consultadoEm`. Se algum escopo não responder, os demais voltam mesmo assim, com `falhas` preenchido. Fonte: Expectativas de Mercado (Focus) do Banco Central do Brasil, via Olinda OData. O Focus é vintage por construção: `coletadoEm` é a data da coleta e `referencia` é o alvo da expectativa — a mesma referência aparece em muitas coletas, e é isso que permite ver a expectativa mudar no tempo. A contagem é feita do nosso lado porque a fonte ignora `$count`; e o filtro é obrigatório por construção porque consulta sem filtro não completa na origem. Microdados por instituição NÃO são expostos: a fonte desativou esse recurso por risco de quebra de confidencialidade.
Parameters2
indicador
string
optional
Filtrar por um indicador específico, para ver em quais escopos ele existe (opcional)
escopo
string
optional
Restringe a descoberta a um escopo (opcional). 'selic' descobre as reuniões do Copom para bcb_focus_selic; os demais são os horizontes de bcb_focus_expectativas.
Raw schema
{
"type": "object",
"properties": {
"indicador": {
"type": "string",
"description": "Filtrar por um indicador específico, para ver em quais escopos ele existe (opcional)"
},
"escopo": {
"type": "string",
"enum": [
"mensal",
"trimestral",
"anual",
"inflacao_12m",
"inflacao_24m",
"selic"
],
"description": "Restringe a descoberta a um escopo (opcional). 'selic' descobre as reuniões do Copom para bcb_focus_selic; os demais são os horizontes de bcb_focus_expectativas."
}
},
"additionalProperties": false
}
bcb_cambio_cotacao
Consulta a cotação PTAX de uma moeda contra o real, em um dia específico ou num intervalo de datas. Padrão: dólar americano (USD). Devolve compra, venda, data/hora e tipo de boletim; para moedas não-dólar devolve também a paridade contra o USD, com a origem qualificada. Quando usar: para a cotação oficial de fechamento de um dia ou a série de um período curto. Quando NÃO usar: para a série histórica longa do dólar como série temporal do SGS use bcb_serie_valores (códigos 1 = livre venda, 3698 = PTAX venda, 3697 = PTAX compra, 3695 = PTAX média) — esta tool é a fonte primária do boletim, com compra e venda no mesmo registro; para descobrir o símbolo da moeda use bcb_cambio_moedas. Retorna: `moeda`, `periodo` (dataInicial, dataFinal, janelaPadrao), `totalRegistros`, `cotacoes`, `disclaimer`, `qualificacaoParidade` (só para moedas não-dólar), `urlConsulta`, `consultadoEm` e, quando aplicável, `observacao`. Sem datas, cobre os últimos 7 dias (para atravessar fim de semana e feriado). Fonte: PTAX / Cotações e boletins de câmbio do Banco Central do Brasil, via Olinda OData. A resposta repassa literalmente o disclaimer de responsabilidade do BCB, em `disclaimer`. Cotações existem só em dia útil com fechamento de câmbio. As paridades de moedas não-dólar vêm de agência de informação (Refinitiv), redistribuídas pelo BCB — não são apuradas pelo Banco Central.
Parameters5
moeda
string
optional
Símbolo da moeda (ex.: USD, EUR, GBP, JPY). Padrão: USD.
data
string
optional
Dia específico (yyyy-MM-dd ou dd/MM/yyyy). Não combine com dataInicial/dataFinal.
dataInicial
string
optional
Início do intervalo (yyyy-MM-dd ou dd/MM/yyyy). Padrão: 7 dias antes do fim.
dataFinal
string
optional
Fim do intervalo (yyyy-MM-dd ou dd/MM/yyyy). Padrão: hoje.
limite
number
optional
Máximo de boletins a devolver (1-1000, padrão 100)
Raw schema
{
"type": "object",
"properties": {
"moeda": {
"type": "string",
"description": "Símbolo da moeda (ex.: USD, EUR, GBP, JPY). Padrão: USD.",
"default": "USD"
},
"data": {
"type": "string",
"description": "Dia específico (yyyy-MM-dd ou dd/MM/yyyy). Não combine com dataInicial/dataFinal."
},
"dataInicial": {
"type": "string",
"description": "Início do intervalo (yyyy-MM-dd ou dd/MM/yyyy). Padrão: 7 dias antes do fim."
},
"dataFinal": {
"type": "string",
"description": "Fim do intervalo (yyyy-MM-dd ou dd/MM/yyyy). Padrão: hoje."
},
"limite": {
"type": "number",
"description": "Máximo de boletins a devolver (1-1000, padrão 100)",
"default": 100,
"minimum": 1,
"maximum": 1000
}
},
"additionalProperties": false
}
bcb_cambio_moedas
Lista as moedas com cotação publicada pelo Banco Central, com símbolo, nome e tipo, e aceita um termo para filtrar. Quando usar: para descobrir o símbolo correto antes de chamar bcb_cambio_cotacao (é a causa mais comum de cotação vazia). Quando NÃO usar: para valores de cotação. Retorna: `termo`, `totalMoedas`, `moedas` (simbolo, nome, tipo), `disclaimer`, `qualificacaoParidade`, `urlConsulta` e `consultadoEm`. Fonte: PTAX / Cotações e boletins de câmbio do Banco Central do Brasil, via Olinda OData. A resposta repassa literalmente o disclaimer de responsabilidade do BCB, em `disclaimer`. Cotações existem só em dia útil com fechamento de câmbio.
Parameters1
termo
string
optional
Filtro por símbolo ou nome (ex.: 'EUR', 'libra'). Opcional.
Raw schema
{
"type": "object",
"properties": {
"termo": {
"type": "string",
"description": "Filtro por símbolo ou nome (ex.: 'EUR', 'libra'). Opcional."
}
},
"additionalProperties": false
}
search
Searches the Banco Central do Brasil time series (SGS: interest rates, inflation, exchange rates, credit, fiscal and external sector — the curated catalog plus the open data portal index) catalog and returns up to 10 matching documents as { id, title, url }, ordered by relevance (an empty list means nothing matched).
This tool exists for the OpenAI Deep Research contract: ChatGPT deep research, company knowledge and research workflows over the Responses API require exactly the tools `search` and `fetch`. Pass one of the returned ids to `fetch` to read the document.
For direct questions and for data (values, series, rankings) prefer the `bcb_*` tools, which return the actual data with provenance — this is a catalog index, not a data query.
Query: natural language or keywords, Portuguese or English; accents and case are ignored.
Behavior: read-only and idempotent — the catalog comes from the public source and is cached in memory.
Parameters1
query
string
required
Termos de busca em linguagem natural ou palavras-chave (acentos e caixa são ignorados)
Raw schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Termos de busca em linguagem natural ou palavras-chave (acentos e caixa são ignorados)"
}
},
"required": [
"query"
],
"additionalProperties": false
}
fetch
Returns the full document for an id obtained from `search`, as { id, title, text, url, metadata }: `text` is the readable content (Markdown) and `url` the canonical public page to cite.
Companion of `search` in the OpenAI Deep Research contract, over the Banco Central do Brasil time series (SGS: interest rates, inflation, exchange rates, credit, fiscal and external sector — the curated catalog plus the open data portal index) catalog. Only ids returned by `search` are valid; an unknown id returns an error.
The `bcb_*` tools remain the tools for data queries.
Behavior: read-only and idempotent — a live GET against the public source when the document needs it.
Parameters1
id
string
required
Identificador de um documento devolvido por `search`
Raw schema
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identificador de um documento devolvido por `search`"
}
},
"required": [
"id"
],
"additionalProperties": false
}
MCP (Model Context Protocol) server for the Brazilian Central Bank (Banco Central do Brasil, BCB): SGS time series (SGS/BCB), the Focus market-expectations survey (served over the Olinda OData API) and PTAX exchange rates.
Query economic and financial indicators such as Selic (interest rate), IPCA (inflation), exchange rates, GDP, and more, directly from AI assistants like Claude.
If you find this project useful, please consider giving it a star on GitHub. It helps others discover the project!
Capabilities: 17 tools (skills) · 3 resources · 3 prompts — everything an MCP client needs to query the Brazilian Central Bank: SGS/BCB time series, the Focus market-expectations survey and PTAX exchange rates.
See it in action
Ask your assistant, in plain Portuguese:
"Qual a taxa Selic atual?" → bcb_indicadores_atuais
"Mostre o IPCA mês a mês em 2024." → bcb_serie_valores
"Qual foi a variação do dólar nos últimos 12 meses?" → bcb_variacao
"O que o mercado espera do IPCA em 2027?" → bcb_focus_expectativas
"Qual a Selic esperada na próxima reunião do Copom?" → bcb_focus_selic
"Qual foi a PTAX de fechamento do euro na sexta?" → bcb_cambio_cotacao
The answers come live from the Brazilian Central Bank's SGS API — exact figures with provenance, not numbers guessed from training data.
Features
Historical data - Query time series values by code with date filters
Latest values - Get the most recent N values of any series
Metadata - Detailed information about series (frequency, source, etc.)
Popular series catalog - 135 economic indicators verified against the source, organized by category
Smart search - Find series by keyword (accent-insensitive)
Current indicators - Latest values for key economic indicators
Long periods, handled - The BCB API caps daily series at a 10-year window
(HTTP 406) and refuses open windows; requests are sliced, fetched and merged
automatically, so a 15-year daily query just works
Frequency harmonisation - Resample a series to monthly, quarterly or annual
with an explicit convention, including geometric compounding for series that
already are percentage changes (monthly IPCA into annual IPCA)
Variation calculation - Percentage change between periods with statistics
Series comparison - Compare multiple series over the same period, with a
warning when their periodicities differ
Focus survey - Market expectations (mean, median, std. deviation, min, max, respondents) for IPCA, GDP, FX and more, by monthly/quarterly/annual horizon or rolling 12/24-month inflation, plus Selic by Copom meeting
PTAX exchange rates - Official closing quotes for any currency the BCB publishes, single day or date range
Query series values by code and date range; slices long windows automatically and can harmonise the series to a coarser frequency
bcb_serie_ultimos
Get the last N values of a series (any N — the upstream cap of 20 is worked around)
bcb_serie_metadados
Get series metadata (name, frequency, category, last value)
bcb_series_populares
List popular series grouped by category
bcb_buscar_serie
Search series by name or description (accent-insensitive, AND between words; everyday words resolved to the BCB's wording, and the response says so)
bcb_indicadores_atuais
Latest values: Selic, IPCA, USD/BRL, IBC-Br
bcb_variacao
Percentage variation of one series over a period: level change for level series, compounded accumulation for series that are already period-on-period rates (IPCA, IGP-M, INPC…); analise.metodo says which
bcb_comparar
Compare 2 to 5 series over the same period with ranking (same level/compounding rule per series, declared in metodo)
bcb_focus_expectativas
Focus survey expectations for one indicator, horizon as a parameter (monthly, quarterly, annual, rolling 12m/24m inflation); top5 flag
bcb_focus_selic
Focus expectations for the Selic rate, by Copom meeting (R1/2026 form)
bcb_focus_referencias
Which indicators and reference dates the Focus survey actually publishes, broken down per scope (the five horizons plus selic, whose axis is the Copom meeting) — the indicator set differs by scope (9 monthly vs 26 annual)
bcb_cambio_cotacao
PTAX quote for a currency (USD by default), single day or date range
bcb_cambio_moedas
Currencies with quotes published by the BCB
search
OpenAI Deep Research contract: searches the series catalog (curated + open data portal index) and returns { id, title, url } — see ChatGPT (Deep Research)
fetch
OpenAI Deep Research contract: returns one series as a readable document with its canonical public URL
Resources
Reference catalogs the server exposes as MCP resources (read-only contextual data that clients can attach):
URI
Description
bcb://series/populares
Catalog of 135 verified BCB economic series, organized by category (JSON)
bcb://series/categorias
List of available categories in the series catalog (JSON)
bcb://series/principais
Codes of the most-used indicators — Selic, IPCA, USD/BRL, GDP, etc. (JSON)
Prompts
Ready-made templates the server provides as MCP prompts:
Generate a complete overview of the Brazilian economy
comparar_inflacao
Compare Brazil's main inflation indices (IPCA, IGP-M, INPC) over the last 12 months
Installation
Via Smithery (recommended)
Visit bcb-br-mcp on Smithery and follow the installation instructions for your MCP client.
Via URL (Claude.ai, Claude Desktop, any MCP client)
Use the HTTP endpoint directly, no installation required:
code
https://bcb.sidneybissoli.com/mcp
The legacy hostname https://bcb.sidneybissoli.workers.dev keeps working, and so
does the older POST / route — clients configured before the endpoint moved to
/mcp are rewritten transparently, so nothing that used to work stopped working.
New setups should use the URL above.
ChatGPT deep research (and company knowledge, and research workflows over the Responses API) only uses an MCP server that exposes exactly search and fetch — this server does, on top of the bcb_* tools. Point the connector at the hosted endpoint, no key required:
code
https://bcb.sidneybissoli.com/mcp
search ranks the query against the series catalog — the 135 curated series plus the thousands indexed from the Open Data Portal — and returns { id, title, url } (ids are sgs:<code>); fetch returns the series as readable Markdown (name, category, frequency, unit, latest value) with the canonical public URL, which is what ChatGPT cites: the dataset page on dadosabertos.bcb.gov.br when the series has one, otherwise the public SGS query for its latest observations (the SGS has no per-series page). Both carry the same provenance block as every other tool. In ChatGPT's developer mode (Settings → Security and login → Developer mode) any tool is callable — the bcb_* tools remain the ones to use for data.
Usage Examples
Get the current Selic rate
code
What is the current Selic interest rate?
→ Uses bcb_indicadores_atuais
IPCA history for 2024
code
Show me the monthly IPCA for 2024
→ Uses bcb_serie_valores with code 433, dataInicial 2024-01-01, dataFinal 2024-12-31
List inflation indicators
code
What inflation series are available?
→ Uses bcb_series_populares with category "Inflação"
Search for USD exchange rate series
code
Search for series related to the dollar
→ Uses bcb_buscar_serie with term "dolar" (works without accents)
Calculate USD/BRL variation
code
What was the USD/BRL variation over the last 12 months?
→ Uses bcb_variacao with code 1 and periodos 12
Compare IPCA, IGP-M, and INPC
code
Compare IPCA, IGP-M, and INPC in 2024
→ Uses bcb_comparar with codes [433, 189, 188], dataInicial 2024-01-01, dataFinal 2024-12-31
Series Catalog (135)
The curated catalog holds 135 series, each verified against the source on 2026-08-13 (4 discontinued FGV series were removed on 2026-08-23).
The fonteNome field on every entry says where its name comes from:
portal (82 series) — the name is transcribed from the series' dataset on the
BCB Open Data Portal, and unidade carries the published unit of measure.
medido (53 series) — the series has no dataset on the portal, so the name is
inherited; what was verified against the source is its periodicity and order of magnitude.
Periodicity is always the measured one (from the spacing between observations), never an
inherited label. Market expectations are not here — use bcb_focus_expectativas.
Juros (14)
Code
Name
Periodicity
Name source
11
Taxa de juros - Selic
Diária
portal
432
Taxa de juros - Meta Selic definida pelo Copom
Diária
portal
1178
Taxa de juros - Selic anualizada base 252
Diária
portal
4189
Taxa de juros - Selic acumulada no mês anualizada base 252
Mensal
portal
4390
Taxa de juros - Selic acumulada no mês
Mensal
portal
12
Taxa de juros - CDI diária
Diária
medido
4389
Taxa de juros - CDI anualizada base 252
Diária
medido
4391
Taxa de juros - CDI acumulada no mês
Mensal
medido
4392
Taxa de juros - CDI acumulada no mês anualizada
Mensal
medido
226
Taxa Referencial (TR) - diária
Diária
medido
7811
Taxa Referencial (TR) - mensal
Mensal
medido
7812
Taxa Referencial (TR) - anualizada
Mensal
medido
256
Taxa de Juros de Longo Prazo (TJLP)
Mensal
medido
253
Taxa de juros - CDB pré-fixado - 30 dias
Diária
medido
Inflação (28)
Code
Name
Periodicity
Name source
433
IPCA - Variação mensal
Mensal
medido
13522
IPCA - Variação acumulada em 12 meses
Mensal
medido
7478
IPCA-15 - Variação mensal
Mensal
medido
10764
IPCA-E - Variação mensal
Mensal
medido
16121
Índice nacional de preços ao consumidor - Amplo (IPCA) - Núcleo por exclusão - ex2
Mensal
portal
16122
Índice nacional de preços ao consumidor - Amplo (IPCA) - Núcleo de dupla ponderação
Mensal
portal
11426
Índice nacional de preços ao consumidor - Amplo (IPCA) - Núcleo médias aparadas sem suavização
Mensal
portal
11427
Índice nacional de preços ao consumidor - Amplo (IPCA) - Núcleo por exclusão - Sem monitorados e alimentos no domicílio
Mensal
portal
10841
Índice de Preços ao Consumidor-Amplo (IPCA) - Bens não-duráveis
Mensal
portal
10842
Índice de Preços ao Consumidor-Amplo (IPCA) - Bens semi-duráveis
Mensal
portal
10843
Índice de Preços ao Consumidor-Amplo (IPCA) - Duráveis
Mensal
portal
10844
Índice de Preços ao Consumidor-Amplo (IPCA) - Serviços
Mensal
portal
4449
Índice nacional de preços ao consumidor-Amplo (IPCA) - Preços monitorados - Total
Mensal
portal
11428
Índice nacional de preços ao consumidor - Amplo (IPCA) - Itens livres
Mensal
portal
188
INPC - Variação mensal
Mensal
medido
189
IGP-M - Variação mensal
Mensal
medido
7447
IGP-10 - Variação mensal
Mensal
medido
7448
IGP-M - 1ª prévia
Mensal
medido
7449
IGP-M - 2ª prévia
Mensal
medido
190
IGP-DI - Variação mensal
Mensal
medido
7450
IPA-M - Variação mensal
Mensal
medido
225
IPA-DI - Geral - Variação mensal
Mensal
medido
7459
IPA-DI - Produtos industriais
Mensal
medido
7460
IPA-DI - Produtos agrícolas
Mensal
medido
191
IPC-DI - Variação mensal
Mensal
medido
193
IPC-Fipe - Variação mensal
Mensal
medido
17679
IPC-3i - Variação mensal
Mensal
medido
17680
IPC-C1 - Variação mensal
Mensal
medido
Câmbio (13)
Code
Name
Periodicity
Name source
1
Taxa de câmbio - Livre - Dólar americano (venda) - diário
Diária
portal
10813
Taxa de câmbio - Livre - Dólar americano (compra)
Diária
portal
3698
Taxa de câmbio - PTAX - Dólar americano (venda)
Mensal
medido
3697
Taxa de câmbio - PTAX - Dólar americano (compra)
Mensal
medido
3695
Taxa de câmbio - PTAX - Dólar americano (média)
Mensal
medido
21619
Taxa de câmbio - Euro (venda)
Diária
medido
21620
Taxa de câmbio - Euro (compra)
Diária
medido
21623
Taxa de câmbio - Libra Esterlina (venda)
Diária
medido
21624
Taxa de câmbio - Libra Esterlina (compra)
Diária
medido
21621
Taxa de câmbio - Iene (venda)
Diária
medido
21622
Taxa de câmbio - Iene (compra)
Diária
medido
21625
Taxa de câmbio - Franco Suíço (venda)
Diária
medido
21626
Taxa de câmbio - Franco Suíço (compra)
Diária
medido
Atividade Econômica (21)
Code
Name
Periodicity
Name source
4380
PIB mensal - Valores correntes (R$ milhões)
Mensal
medido
4381
PIB acumulado no ano - Valores correntes (R$ milhões)
Mensal
medido
4382
PIB acumulado dos últimos 12 meses - Valores correntes (R$ milhões)
Mensal
medido
4385
PIB mensal em US$ (milhões)
Mensal
medido
4386
PIB acumulado no ano em US$ (milhões)
Mensal
medido
7324
PIB anual em US$ (milhões)
Anual
medido
24363
Índice de Atividade Econômica do Banco Central - IBC-Br
Mensal
portal
24364
Índice de Atividade Econômica do Banco Central (IBC-Br) - com ajuste sazonal
Mensal
portal
29601
Índice de Atividade Econômica do Banco Central (IBC-Br) Agropecuária
Mensal
portal
29602
Índice de Atividade Econômica do Banco Central (IBC-Br) Agropecuária - com ajuste sazonal
Mensal
portal
29603
Índice de Atividade Econômica do Banco Central (IBC-Br) Indústria
Mensal
portal
29604
Índice de Atividade Econômica do Banco Central (IBC-Br) Indústria - com ajuste sazonal
Mensal
portal
29605
Índice de Atividade Econômica do Banco Central (IBC-Br) Serviços
Mensal
portal
29606
Índice de Atividade Econômica do Banco Central (IBC-Br) Serviços - com ajuste sazonal
Mensal
portal
22103
Exportação de bens e serviços - Trimestral
Trimestral
medido
22104
Importação de bens e serviços - Trimestral
Trimestral
medido
22109
Consumo das famílias - Trimestral
Trimestral
medido
22110
Consumo do governo - Trimestral
Trimestral
medido
22111
Formação bruta de capital fixo - Trimestral
Trimestral
medido
21859
Produção industrial - Geral - Variação mensal
Mensal
medido
21862
Utilização da capacidade instalada - Indústria
Mensal
medido
Emprego (4)
Code
Name
Periodicity
Name source
24369
Taxa de desocupação - PNAD Contínua
Mensal
medido
24380
Rendimento médio real habitual - Todos os trabalhos
Mensal
medido
24381
Massa de rendimento real habitual
Mensal
medido
28561
CAGED - Saldo de empregos formais
Mensal
medido
Fiscal (7)
Code
Name
Periodicity
Name source
4503
Dívida Líquida do Setor Público (% PIB) - Total - Governo Federal e Banco Central
Mensal
portal
4513
Dívida Líquida do Setor Público (% PIB) - Total - Setor público consolidado
Mensal
portal
4505
Dívida Líquida do Setor Público (% PIB) - Total - Banco Central
Mensal
portal
4536
Dívida líquida do governo geral (% PIB)
Mensal
portal
4537
Dívida bruta do governo geral (% PIB) - Metodologia utilizada até 2007
Mensal
portal
5364
Receita total do governo central
Mensal
medido
5793
NFSP sem desvalorização cambial (% PIB) - Fluxo acumulado em 12 meses - Resultado primário - Total - Setor público consolidado
Mensal
portal
Setor Externo (12)
Code
Name
Periodicity
Name source
3546
Reservas internacionais - Conceito liquidez - Total
Mensal
medido
13621
Reservas internacionais - Conceito caixa - Total - diária
Diária
portal
22707
Balança comercial - Balanço de Pagamentos - mensal - saldo
Mensal
portal
22708
Exportação de bens - Balanço de Pagamentos - mensal
Mensal
portal
22709
Importação de bens - Balanço de Pagamentos - mensal
Mensal
portal
22714
Bens exportados sob merchanting - exportações positivas - mensal
Mensal
portal
22701
Transações correntes - mensal - saldo
Mensal
portal
22704
Balança comercial e Serviços - mensal - saldo
Mensal
portal
22715
Bens importados sob merchanting - exportações negativas - mensal
Mensal
portal
22716
Balança comercial - ouro não monetário - Balanço de Pagamentos - mensal - saldo
Investimentos diretos no país - IDP - mensal - líquido
Mensal
portal
Crédito (30)
Code
Name
Periodicity
Name source
20539
Saldo da carteira de crédito - Total
Mensal
portal
20540
Saldo da carteira de crédito - Pessoas jurídicas - Total
Mensal
portal
20541
Saldo da carteira de crédito - Pessoas físicas - Total
Mensal
portal
20542
Saldo da carteira de crédito com recursos livres - Total
Mensal
portal
20570
Saldo da carteira de crédito com recursos livres - Pessoas físicas - Total
Mensal
portal
20592
Saldo da carteira de crédito com recursos livres - Pessoas físicas - Outros créditos livres
Mensal
portal
20615
Saldo da carteira de crédito com recursos direcionados - Pessoas físicas - Financiamento agroindustrial com recursos do BNDES
Mensal
portal
20631
Concessões de crédito - Total
Mensal
portal
20665
Concessões de crédito com recursos livres - Pessoas físicas - Cheque especial
Mensal
portal
20714
Taxa média de juros das operações de crédito - Total
Mensal
portal
20716
Taxa média de juros das operações de crédito - Pessoas físicas - Total
Mensal
portal
20740
Taxa média de juros das operações de crédito com recursos livres - Pessoas físicas - Total
Mensal
portal
20749
Taxa média de juros das operações de crédito com recursos livres - Pessoas físicas - Aquisição de veículos
Mensal
portal
20772
Taxa média de juros das operações de crédito com recursos direcionados - Pessoas físicas - Financiamento imobiliário com taxas de mercado
Mensal
portal
25497
Taxa média mensal de juros das operações de crédito com recursos direcionados - Pessoas físicas - Financiamento imobiliário com taxas de mercado
Mensal
portal
20783
Spread médio das operações de crédito - Total
Mensal
portal
20785
Spread médio das operações de crédito - Pessoas físicas - Total
Mensal
portal
20786
Spread médio das operações de crédito com recursos livres - Total
Mensal
portal
21082
Inadimplência da carteira de crédito - Total
Mensal
portal
21084
Inadimplência da carteira de crédito - Pessoas físicas - Total
Mensal
portal
21085
Inadimplência da carteira de crédito com recursos livres - Total
Mensal
portal
21128
Inadimplência da carteira de crédito com recursos livres - Pessoas físicas - Cartão de crédito parcelado
Mensal
portal
21129
Inadimplência da carteira de crédito com recursos livres - Pessoas físicas - Cartão de crédito total
Mensal
portal
13685
Inadimplência da carteira de crédito das instituições financeiras sob controle privado - Total
Mensal
portal
29033
Comprometimento de renda das famílias com juros da dívida com o Sistema Financeiro Nacional - Com ajuste sazonal (RNDBF)
Mensal
portal
29034
Comprometimento de renda das famílias com o serviço da dívida com o Sistema Financeiro Nacional - Com ajuste sazonal (RNDBF)
Mensal
portal
29035
Comprometimento de renda das famílias com o serviço da dívida com o Sistema Financeiro Nacional exceto crédito habitacional - Com ajuste sazonal (RNDBF)
Mensal
portal
29036
Comprometimento de renda das famílias com amortização da dívida com o Sistema Financeiro Nacional - Com ajuste sazonal (RNDBF)
Mensal
portal
29037
Endividamento das famílias com o Sistema Financeiro Nacional em relação à renda acumulada dos últimos doze meses (RNDBF)
Mensal
portal
29038
Endividamento das famílias com o Sistema Financeiro Nacional exceto crédito habitacional em relação à renda acumulada dos últimos 12 meses (RNDBF)
Mensal
portal
Agregados Monetários (8)
Code
Name
Periodicity
Name source
1788
BM - Base monetária restrita (saldo em final de período)
Mensal
portal
1833
Base Monetária Ampliada (saldo em final de período)
Mensal
portal
27788
Meios de pagamento - M1 (média dos dias úteis do mês) - Novo
Mensal
portal
27789
Meios de pagamento - Papel moeda em poder do público (saldo em final de período) - Novo
Mensal
portal
27790
Meios de pagamento - Depósitos à vista (saldo em final de período) - Novo
Mensal
portal
27791
Meios de pagamento - M1 (saldo em final de período) - Novo
Mensal
portal
27815
Meios de pagamento amplos - M4 (saldo em final de periodo) - Novo
Mensal
portal
7530
Comportamento monetário - Comportamento do público - C
Mensal
portal
Poupança (2)
Code
Name
Periodicity
Name source
25
Depósitos de poupança até 03.05.2012 - Rentabilidade no período
Diária
portal
195
Depósitos de poupança a partir de 04.05.2012 - Rentabilidade no período
Diária
portal
The full machine-readable catalog is served as the bcb://series/populares resource and by
bcb_series_populares. Thousands of further series are reachable through bcb_buscar_serie,
which also queries the BCB Open Data Portal index.
Finding Other Series
The SGS database contains over 18,000 time series. To find codes for other series:
bcb_buscar_serie matches your words, all of them (AND), against the curated catalogue (135 series: name and category) and the dataset slugs of the BCB open-data portal (3,579 series identified by code). Accents were already ignored; the word was not. Measured over both layers on 2026-09-16, fixed since 1.12.0: the everyday word is expanded to the BCB's own, and the response says so in notasVocabulario; zero results come with a way out.
you ask
hits before (curated / portal)
the BCB writes
hits
déficit, superávit
0 / 0
resultado primário, resultado nominal
1 / 26, 0 / 22
calote
0 / 0
inadimplência
6 / 484
juros básicos
0 / 0
Selic
5 / 7
desemprego
0 / 0
desocupação
1 / 0
arrecadação, gasto
0 / 0
receita, despesa
2 / 8, 0 / 8
investimento estrangeiro
0 / 0
investimento direto
1 / 12
conta corrente
0 / 0
transações correntes
1 / 5
Only measured pairs enter the table (src/vocabulario.ts): the word you ask with absent from both layers, the BCB's word present. What the BCB does not publish under any of these names stays out and still returns zero — salário mínimo, ibovespa, bitcoin, meta de inflação — because an alias for a series that does not exist promises what the source does not have; and empréstimo is not mapped to crédito on purpose (the portal already answers it with 45 datasets; the mapping would drown them in 2,000). The same table feeds the Deep Research search index.
Technical Details
Robustness
Timeout: 30 seconds per request (prevents hanging)
Auto-retry: 3 attempts with exponential backoff (1s, 2s, 4s) for transient
failures; client errors (4xx) are not retried, since they are deterministic
Error handling: Clear error messages
Working around the SGS limits
Measured against the live API, not inferred from documentation:
A date window over 10 years on a daily series is refused with HTTP 406,
and so is an open window (no dataInicial, or no dates at all). The limit
applies to the implicit window: with no dataFinal the API assumes today.
Requests are sliced into windows of up to 3 years, fetched with bounded
concurrency and merged in date order without duplicating the seams; the response
reports it in chunking. The slice is 3 years rather than the allowed 10 because
a 10-year daily window costs 10–20 s upstream and may be cut off around 30 s.
dados/ultimos/N is capped at 20 by the API, in every periodicity. Above 20,
the server infers the series' periodicity and fetches by date window instead.
There is no per-series metadata endpoint (/metadados answers 404). Frequency
is inferred from the spacing of the observations and flagged with
periodicidadeInferida; unit of measure is not available from any source.
Derived values
Anything this server computes — variation, descriptive statistics, harmonised
series — is marked derived: true and carries a note with the conventions used.
Statistics come from @sbissoli/mcp-stats.
A value published by the BCB is always returned verbatim; only computed values are
rounded (to 4 decimals).
Smart Search
bcb_buscar_serie searches two layers: the curated catalog of 135 verified series (which ranks first, with
the source of the name declared) and the index of the BCB Open Data Portal, with thousands of series
identified by code. Terms are accent- and case-insensitive, and several terms are combined with AND:
"inflacao" → finds "Inflação"
"cambio" → finds "Câmbio"
"ipca servicos" → both terms must match
The portal index is served from a 24-hour cache, renewed by the first search after it expires (one request to
the portal, only metadata — series codes and names, never observations). Every answer carries
catalogo.cobertura: the index is not the whole SGS, so not finding a series here is not proof it does not
exist.
Data source and licence
Data obtained from the Banco Central do Brasil (SGS / Olinda-Expectativas / PTAX), published under the
Open Data Commons Open Database License (ODbL) v1.0 — https://opendatacommons.org/licenses/odbl/1-0/.
Re-verified against the source on 2026-08-13: 4,259 of the portal's 4,260 datasets declare
license_id: "odc-odbl". This is not CC0, CC BY, or public domain — ODbL carries attribution,
share-alike (on derived databases) and anti-DRM clauses. Exchange-rate answers pass through the BCB's own
liability disclaimer verbatim; cross-currency parities are not compiled by the BCB — they come from an
information agency (Refinitiv) and are redistributed by the BCB, and the tools say so.
The server's own code is MIT; the data is not. See NOTICE.md. Privacy: no user data is logged, by either channel — see PRIVACY.md.
Provenance block
Every successful tool response carries a provenance block (portfolio contract v1.0) in two channels:
structuredContent.provenance + attribution (visible to the model) and a _meta mirror under
br.com.sidneybissoli.bcb/* (out of band, zero tokens). Each block names the source, the canonical URL that
reproduces the query, the data vintage, the real upstream extraction instant, and the licence.
Two details that are easy to get wrong and are handled here:
retrieved_at is the real extraction instant, not "now". The portal index is served from a 24-hour
cache, so a search answered from cache reports the instant the index was actually fetched — which can be a
day old, and is the legally relevant date.
One block per provenance, never merged.bcb_buscar_serie separates the BCB portal index from the
server's own curated catalogue; bcb_serie_metadados separates the live SGS reading from the catalogue;
bcb_cambio_cotacao separates BCB-compiled dollar rates from agency-sourced cross-currency parities.
Development
Requirements
Node.js >= 18.0.0
Setup
bash
git clone https://github.com/SidneyBissoli/bcb-br-mcp.git
cd bcb-br-mcp
npm install
Build
bash
npm run build
Local testing (stdio)
bash
npm run dev
Local testing (HTTP worker)
bash
npm run dev:worker
Or use the MCP Inspector:
bash
npx @modelcontextprotocol/inspector npm run dev
BCB API
This server uses the Brazilian Central Bank's public API:
Base endpoint:https://api.bcb.gov.br/dados/serie/bcdata.sgs.{code}/dados
bcb_focus_referencias: the parameter is now escopo, not horizonte, and the
response array is escopos. The scopes are the five horizons of
bcb_focus_expectativasplus selic — and selic is not a horizon: its
axis is the Copom meeting. Each block names the tool that consumes it. The
previous name implied selic was a queryable horizon of
bcb_focus_expectativas, which it is not. Never published to npm under the old
name.
v1.4.0
Three APIs under one contract, 8 tools → 13. Focus market-expectations
survey (bcb_focus_expectativas, bcb_focus_selic, bcb_focus_referencias)
and PTAX exchange rates (bcb_cambio_cotacao, bcb_cambio_moedas), consolidated
by parameter rather than mirroring the source's ~18 OData resources.
Real search.bcb_buscar_serie now queries the Open Data Portal index
(3,500+ series, 24-hour cache, metadata only) on top of the curated catalog, and
states the index's coverage instead of claiming a series does not exist.
Every Focus and PTAX field name verified against the live API, including the
Top 5 Selic resource, which publishes its fields in a different case from the
other twelve.
ODbL obligations shipped with the exchange-rate tools: the BCB disclaimer is
passed through verbatim, and non-USD parities are qualified as third-party
(Refinitiv) data redistributed by the BCB.
v1.2.0
HTTP endpoint via Cloudflare Workers (https://bcb.sidneybissoli.workers.dev)
Published on Smithery.ai
Refactored: tool logic extracted to src/tools.ts (shared between stdio and HTTP)
v1.1.0
New tool bcb_variacao for percentage variation calculation
New tool bcb_comparar for comparing multiple series
30-second timeout on requests
Auto-retry with exponential backoff (3 attempts)
Normalized search (accent-insensitive)
Additional statistics (max, min, average, range)
v1.0.0
Initial release
6 basic tools
Catalog with 135 verified series
Contributing
Contributions are welcome! Please:
Fork the repository
Create a feature branch (git checkout -b feature/new-feature)
Commit your changes (git commit -m 'Add new feature')
Push to the branch (git push origin feature/new-feature)
Data: from the Banco Central do Brasil, under the Open Data Commons Open
Database License (ODbL) v1.0 — https://opendatacommons.org/licenses/odbl/1-0/.
Not CC0, not CC BY, not public domain: the ODbL requires attribution, has a
share-alike clause on derived databases, and an anti-DRM clause.
Every successful response carries a provenance block with the source, the query URL, the data vintage, the
real extraction instant and the licence. Exchange-rate answers pass the BCB disclaimer through verbatim, and
non-USD parities are qualified as information-agency data (Refinitiv) redistributed by the BCB — not as data
compiled by the Central Bank.
Details and obligations in NOTICE.md. Privacy: no user data is logged, by either channel — see PRIVACY.md.
