BCB BR MCP

Banco Central do Brasil (BCB) — Servidor MCP de Séries Temporais SGS

Leia em Português

Servidor MCP (Model Context Protocol) para o Banco Central do Brasil (BCB): séries temporais SGS (SGS/BCB), a pesquisa de expectativas de mercado Focus (servida pela API OData Olinda) e taxas de câmbio PTAX.

Consulte indicadores econômicos e financeiros como Selic (taxa de juros), IPCA (inflação), taxas de câmbio, PIB e muito mais, diretamente de assistentes de IA como Claude.

Se você achar este projeto útil, considere dar uma estrela no GitHub. Isso ajuda outras pessoas a descobrirem o projeto!

Recursos: 17 ferramentas (habilidades) · 3 recursos · 3 prompts — tudo o que um cliente MCP precisa para consultar o Banco Central do Brasil: séries temporais SGS/BCB, a pesquisa de expectativas de mercado Focus e taxas de câmbio PTAX.

Veja em ação

Pergunte ao seu assistente, em português simples:

• "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

As respostas vêm ao vivo da API SGS do Banco Central do Brasil — números exatos com procedência, não valores adivinhados a partir de dados de treinamento.

Recursos

• Dados históricos - Consulte valores de séries temporais por código com filtros de data
• Valores mais recentes - Obtenha os N valores mais recentes de qualquer série
• Metadados - Informações detalhadas sobre as séries (frequência, fonte, etc.)
• Catálogo de séries populares - 135 indicadores econômicos verificados junto à fonte, organizados por categoria
• Busca inteligente - Encontre séries por palavra-chave (insensível a acentos)
• Indicadores atuais - Valores mais recentes dos principais indicadores econômicos
• Períodos longos, resolvidos - A API do BCB limita séries diárias a uma janela de 10 anos (HTTP 406) e recusa janelas abertas; as solicitações são fatiadas, buscadas e mescladas automaticamente, então uma consulta diária de 15 anos simplesmente funciona
• Harmonização de frequência - Reamostre uma série para mensal, trimestral ou anual com uma convenção explícita, incluindo composição geométrica para séries que já são variações percentuais (IPCA mensal em IPCA anual)
• Cálculo de variação - Variação percentual entre períodos com estatísticas
• Comparação de séries - Compare múltiplas séries no mesmo período, com um aviso quando as periodicidades diferem
• Pesquisa Focus - Expectativas de mercado (média, mediana, desvio padrão, mínimo, máximo, respondentes) para IPCA, PIB, câmbio e mais, por horizonte mensal/trimestral/anual ou inflação móvel de 12/24 meses, além da Selic por reunião do Copom
• Taxas de câmbio PTAX - Cotações oficiais de fechamento para qualquer moeda publicada pelo BCB, em um único dia ou intervalo de datas

📖 Artigo (em português): Séries do Banco Central: como consultar o SGS, a Focus e a PTAX sem cair nas armadilhas — os três limites da API medidos ao vivo, séries de nível vs. taxa, os escopos da Focus e o que a ODbL exige. Também publicado no site, em português e inglês: sidneybissoli.com.

Ferramentas Disponíveis

Ferramenta	Descrição
bcb_serie_valores	Consulta valores de séries por código e intervalo de datas; fatia janelas longas automaticamente e pode harmonizar a série para uma frequência mais grossa
bcb_serie_ultimos	Obtém os últimos N valores de uma série (qualquer N — o limite upstream de 20 é contornado)
bcb_serie_metadados	Obtém metadados da série (nome, frequência, categoria, último valor)
bcb_series_populares	Lista séries populares agrupadas por categoria
bcb_buscar_serie	Busca séries por nome ou descrição (insensível a acentos, E entre palavras; palavras comuns resolvidas para a terminologia do BCB, e a resposta informa isso)
bcb_indicadores_atuais	Valores mais recentes: Selic, IPCA, USD/BRL, IBC-Br
bcb_variacao	Variação percentual de uma série em um período: variação de nível para séries de nível, acumulação composta para séries que já são taxas período a período (IPCA, IGP-M, INPC…); analise.metodo informa qual
bcb_comparar	Compara 2 a 5 séries no mesmo período com classificação (mesma regra de nível/composição por série, declarada em metodo)
bcb_focus_expectativas	Expectativas da pesquisa Focus para um indicador, horizonte como parâmetro (mensal, trimestral, anual, inflação móvel 12m/24m); flag top5
bcb_focus_selic	Expectativas Focus para a taxa Selic, por reunião do Copom (formato R1/2026)
bcb_focus_referencias	Quais indicadores e datas de referência a pesquisa Focus realmente publica, detalhados por escopo (os cinco horizontes mais selic, cujo eixo é a reunião do Copom) — o conjunto de indicadores difere por escopo (9 mensais vs 26 anuais)
bcb_cambio_cotacao	Cotação PTAX para uma moeda (USD por padrão), em um único dia ou intervalo de datas
bcb_cambio_moedas	Moedas com cotações publicadas pelo BCB
search	Contrato OpenAI Deep Research: busca no catálogo de séries (curado + índice do portal de dados abertos) e retorna { id, title, url } — veja ChatGPT (Deep Research)
fetch	Contrato OpenAI Deep Research: retorna uma série como documento legível com sua URL pública canônica

Recursos

Catálogos de referência que o servidor expõe como recursos MCP (dados contextuais somente leitura que os clientes podem anexar):

URI	Descrição
bcb://series/populares	Catálogo de 135 séries econômicas verificadas do BCB, organizado por categoria (JSON)
bcb://series/categorias	Lista de categorias disponíveis no catálogo de séries (JSON)
bcb://series/principais	Códigos dos indicadores mais usados — Selic, IPCA, USD/BRL, PIB, etc. (JSON)

Prompts

Modelos prontos que o servidor fornece como prompts MCP:

Prompt	Descrição
indicadores_atuais	Consulta os principais indicadores econômicos do Brasil (Selic, IPCA, USD/BRL, IBC-Br)
panorama_economico	Gera uma visão geral completa da economia brasileira
comparar_inflacao	Compara os principais índices de inflação do Brasil (IPCA, IGP-M, INPC) nos últimos 12 meses

Instalação

Via Smithery (recomendado)

Visite bcb-br-mcp no Smithery e siga as instruções de instalação para o seu cliente MCP.

Via URL (Claude.ai, Claude Desktop, qualquer cliente MCP)

Use o endpoint HTTP diretamente, sem necessidade de instalação:

https://bcb.sidneybissoli.com/mcp

O hostname legado https://bcb.sidneybissoli.workers.dev continua funcionando, assim como a rota mais antiga POST / — clientes configurados antes do endpoint mudar para /mcp são reescritos de forma transparente, então nada que funcionava parou de funcionar. Novas configurações devem usar a URL acima.

Via npx (Claude Desktop)

Adicione ao arquivo de configuração do Claude Desktop:

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bcb-br": {
      "command": "npx",
      "args": ["-y", "bcb-br-mcp"]
    }
  }
}

Via instalação global

npm install -g bcb-br-mcp

{
  "mcpServers": {
    "bcb-br": {
      "command": "bcb-br-mcp"
    }
  }
}

ChatGPT (Deep Research)

O deep research do ChatGPT (e conhecimento da empresa, e fluxos de trabalho de pesquisa via Responses API) só usa um servidor MCP que expõe exatamente search e fetch — este servidor expõe, além das bcb_* ferramentas. Aponte o conector para o endpoint hospedado, sem necessidade de chave:

https://bcb.sidneybissoli.com/mcp

search classifica a consulta contra o catálogo de séries — as 135 séries curadas mais as milhares indexadas do Portal de Dados Abertos — e retorna { id, title, url } (os ids são sgs:<code>); fetch retorna a série como Markdown legível (nome, categoria, frequência, unidade, último valor) com a URL pública canônica, que é o que o ChatGPT cita: a página do conjunto de dados em dadosabertos.bcb.gov.br quando a série tem uma, caso contrário a consulta pública SGS para suas observações mais recentes (o SGS não tem página por série). Ambos carregam o mesmo bloco de procedência que todas as outras ferramentas. No modo desenvolvedor do ChatGPT (Configurações → Segurança e login → Modo desenvolvedor), qualquer ferramenta pode ser chamada — as ferramentas bcb_* continuam sendo as recomendadas para dados.

Exemplos de Uso

Obter a taxa Selic atual

What is the current Selic interest rate?
→ Uses bcb_indicadores_atuais

Histórico do IPCA para 2024

Show me the monthly IPCA for 2024
→ Uses bcb_serie_valores with code 433, dataInicial 2024-01-01, dataFinal 2024-12-31

Listar indicadores de inflação

What inflation series are available?
→ Uses bcb_series_populares with category "Inflação"

Buscar séries de taxa de câmbio USD

Search for series related to the dollar
→ Uses bcb_buscar_serie with term "dolar" (works without accents)

Calcular variação USD/BRL

What was the USD/BRL variation over the last 12 months?
→ Uses bcb_variacao with code 1 and periodos 12

Comparar IPCA, IGP-M e INPC

Compare IPCA, IGP-M, and INPC in 2024
→ Uses bcb_comparar with codes [433, 189, 188], dataInicial 2024-01-01, dataFinal 2024-12-31

Catálogo de Séries (135)

O catálogo curado contém 135 séries, cada uma verificada junto à fonte em 2026-08-13 (4 séries descontinuadas da FGV foram removidas em 2026-08-23).

O campo fonteNome em cada entrada informa de onde vem o nome:

• portal (82 séries) — o nome é transcrito do conjunto de dados da série no Portal de Dados Abertos do BCB, e unidade carrega a unidade de medida publicada.
• medido (53 séries) — a série não tem conjunto de dados no portal, então o nome é herdado; o que foi verificado junto à fonte é sua periodicidade e ordem de grandeza.

A periodicidade é sempre a medida (a partir do espaçamento entre observações), nunca um rótulo herdado. Expectativas de mercado não estão aqui — use bcb_focus_expectativas.

Juros (14)

Código	Nome	Periodicidade	Fonte do nome
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)

Código	Nome	Periodicidade	Fonte do nome
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)

Código	Nome	Periodicidade	Fonte do nome
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)

Código	Nome	Periodicidade	Fonte do nome
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)

Código	Nome	Periodicidade	Fonte do nome
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)

Código	Nome	Periodicidade	Fonte do nome
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)

Código	Nome	Periodicidade	Fonte do nome
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	Mensal	portal
22846	Renda secundária - Demais setores - Transferências pessoais - mensal - receita	Mensal	portal
22885	Investimentos diretos no país - IDP - mensal - líquido	Mensal	portal

Crédito (30)

Código	Nome	Periodicidade	Fonte do nome
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)

Código	Nome	Periodicidade	Fonte do nome
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 período) - Novo	Mensal	portal
7530	Comportamento monetário - Comportamento do público - C	Mensal	portal

Poupança (2)

Código	Nome	Periodicidade	Fonte do nome
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

O catálogo completo legível por máquina é servido como o recurso bcb://series/populares e por bcb_series_populares. Milhares de outras séries são acessíveis por meio de bcb_buscar_serie, que também consulta o índice do Portal de Dados Abertos do BCB.

Encontrando Outras Séries

O banco de dados SGS contém mais de 18.000 séries temporais. Para encontrar códigos de outras séries:

1. Visite o Portal SGS do BCB
2. Pesquise a série desejada
3. Anote o código da série
4. Use esse código com as ferramentas deste servidor

Pergunte com suas palavras, não com as do BCB

bcb_buscar_serie combina suas palavras, todas elas (E), com o catálogo curado (135 séries: nome e categoria) e com os slugs de conjuntos de dados do portal de dados abertos do BCB (3.579 séries identificadas por código). Acentos já eram ignorados; a palavra não era. Medido em ambas as camadas em 16/09/2026, corrigido desde a versão 1.12.0: a palavra do dia a dia é expandida para a palavra do próprio BCB, e a resposta informa isso em notasVocabulario; resultados zero vêm com uma saída.

você pergunta	resultados antes (curado / portal)	o BCB escreve	resultados
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

Apenas pares medidos entram na tabela (src/vocabulario.ts): a palavra que você usa ausente em ambas as camadas, a palavra do BCB presente. O que o BCB não publica sob nenhum desses nomes fica de fora e ainda retorna zero — salário mínimo, ibovespa, bitcoin, meta de inflação — porque um alias para uma série que não existe promete o que a fonte não tem; e empréstimo não é mapeado para crédito de propósito (o portal já responde com 45 conjuntos de dados; o mapeamento os afogaria em 2.000). A mesma tabela alimenta o índice de Deep Research search.

Detalhes Técnicos

Robustez

• Tempo limite: 30 segundos por solicitação (evita travamentos)
• Repetição automática: 3 tentativas com backoff exponencial (1s, 2s, 4s) para falhas transitórias; erros de cliente (4xx) não são repetidos, pois são determinísticos
• Tratamento de erros: Mensagens de erro claras

Contornando os limites do SGS

Medido contra a API ao vivo, não inferido da documentação:

• Uma janela de datas acima de 10 anos em uma série diária é recusada com HTTP 406, assim como uma janela aberta (sem dataInicial, ou sem datas). O limite se aplica à janela implícita: sem dataFinal, a API assume hoje. As solicitações são divididas em janelas de até 3 anos, buscadas com concorrência limitada e mescladas em ordem de data sem duplicar as emendas; a resposta informa isso em chunking. A fatia é de 3 anos em vez dos 10 permitidos porque uma janela diária de 10 anos custa 10–20 s a montante e pode ser cortada em torno de 30 s.
• dados/ultimos/N é limitado a 20 pela API, em todas as periodicidades. Acima de 20, o servidor infere a periodicidade da série e busca por janela de datas.
• Não há endpoint de metadados por série (/metadados responde 404). A frequência é inferida do espaçamento das observações e sinalizada com periodicidadeInferida; a unidade de medida não está disponível em nenhuma fonte.

Valores derivados

Qualquer coisa que este servidor calcula — variação, estatísticas descritivas, séries harmonizadas — é marcada com derived: true e traz uma nota com as convenções usadas. As estatísticas vêm de @sbissoli/mcp-stats. Um valor publicado pelo BCB é sempre retornado literalmente; apenas valores calculados são arredondados (para 4 casas decimais).

Busca Inteligente

bcb_buscar_serie pesquisa duas camadas: o catálogo curado de 135 séries verificadas (que classifica primeiro, com a fonte do nome declarada) e o índice do Portal de Dados Abertos do BCB, com milhares de séries identificadas por código. Os termos são insensíveis a acentos e maiúsculas/minúsculas, e vários termos são combinados com E:

• "inflacao" → encontra "Inflação"
• "cambio" → encontra "Câmbio"
• "ipca servicos" → ambos os termos devem corresponder

O índice do portal é servido a partir de um cache de 24 horas, renovado pela primeira busca após expirar (uma solicitação ao portal, apenas metadados — códigos e nomes de séries, nunca observações). Cada resposta traz catalogo.cobertura: o índice não é o SGS inteiro, então não encontrar uma série aqui não é prova de que ela não existe.

Fonte de dados e licença

Dados obtidos do Banco Central do Brasil (SGS / Olinda-Expectativas / PTAX), publicados sob a Open Data Commons Open Database License (ODbL) v1.0 — https://opendatacommons.org/licenses/odbl/1-0/. Re-verificado contra a fonte em 13/08/2026: 4.259 dos 4.260 conjuntos de dados do portal declaram license_id: "odc-odbl". Esta não é CC0, CC BY ou domínio público — a ODbL traz atribuição, compartilhamento pela mesma licença (em bancos de dados derivados) e cláusulas anti-DRM. As respostas de taxa de câmbio passam pelo aviso de responsabilidade do próprio BCB literalmente; as paridades entre moedas não são compiladas pelo BCB — elas vêm de uma agência de informações (Refinitiv) e são redistribuídas pelo BCB, e as ferramentas informam isso.

O código do próprio servidor é MIT; os dados não são. Veja NOTICE.md. Privacidade: nenhum dado do usuário é registrado, por nenhum canal — veja PRIVACY.md.

Bloco de proveniência

Toda resposta bem-sucedida de ferramenta traz um bloco de proveniência (contrato de portfólio v1.0) em dois canais: structuredContent.provenance + attribution (visível ao modelo) e um espelho _meta sob br.com.sidneybissoli.bcb/* (fora de banda, zero tokens). Cada bloco nomeia a fonte, a URL canônica que reproduz a consulta, a safra dos dados, o instante real de extração a montante e a licença.

Dois detalhes fáceis de errar e tratados aqui:

• retrieved_at é o instante real de extração, não "agora". O índice do portal é servido a partir de um cache de 24 horas, então uma busca respondida do cache informa o instante em que o índice foi realmente buscado — que pode ter um dia, e é a data legalmente relevante.
• Um bloco por proveniência, nunca mesclado. bcb_buscar_serie separa o índice do portal do BCB do catálogo curado do próprio servidor; bcb_serie_metadados separa a leitura ao vivo do SGS do catálogo; bcb_cambio_cotacao separa as taxas de dólar compiladas pelo BCB das paridades entre moedas de fonte de agência.

Desenvolvimento

Requisitos

• Node.js >= 18.0.0

Configuração

git clone https://github.com/SidneyBissoli/bcb-br-mcp.git
cd bcb-br-mcp
npm install

Build

npm run build

Teste local (stdio)

npm run dev

Teste local (worker HTTP)

npm run dev:worker

Ou use o MCP Inspector:

npx @modelcontextprotocol/inspector npm run dev

API do BCB

Este servidor usa a API pública do Banco Central do Brasil:

• Endpoint base: https://api.bcb.gov.br/dados/serie/bcdata.sgs.{code}/dados
• Formato: JSON
• Autenticação: Nenhuma (API pública)
• Documentação: Dados Abertos do BCB

Histórico de versões

v1.4.1

• bcb_focus_referencias: o parâmetro agora é escopo, não horizonte, e o array de resposta é escopos. Os escopos são os cinco horizontes de bcb_focus_expectativas mais selic — e selic não é um horizonte: seu eixo é a reunião do Copom. Cada bloco nomeia o tool que o consome. O nome anterior implicava que selic era um horizonte consultável de bcb_focus_expectativas, o que não é. Nunca foi publicado no npm sob o nome antigo.

v1.4.0

• Três APIs sob um único contrato, 8 ferramentas → 13. Foco na pesquisa de expectativas de mercado (bcb_focus_expectativas, bcb_focus_selic, bcb_focus_referencias) e nas taxas de câmbio PTAX (bcb_cambio_cotacao, bcb_cambio_moedas), consolidadas por parâmetro em vez de espelhar os ~18 recursos OData da fonte.
• Busca real. bcb_buscar_serie agora consulta o índice do Portal de Dados Abertos (mais de 3.500 séries, cache de 24 horas, apenas metadados) além do catálogo curado, e informa a cobertura do índice em vez de afirmar que uma série não existe.
• Cada nome de campo do Focus e da PTAX foi verificado contra a API ao vivo, incluindo o recurso Top 5 Selic, que publica seus campos em um formato de caixa diferente dos outros doze.
• Obrigações da ODbL incluídas nas ferramentas de taxa de câmbio: o aviso legal do BCB é repassado integralmente, e as paridades não-USD são qualificadas como dados de terceiros (Refinitiv) redistribuídos pelo BCB.

v1.2.0

• Endpoint HTTP via Cloudflare Workers (https://bcb.sidneybissoli.workers.dev)
• Publicado no Smithery.ai
• Refatorado: a lógica das ferramentas foi extraída para src/tools.ts (compartilhada entre stdio e HTTP)

v1.1.0

• Nova ferramenta bcb_variacao para cálculo de variação percentual
• Nova ferramenta bcb_comparar para comparar múltiplas séries
• Timeout de 30 segundos nas requisições
• Nova tentativa automática com backoff exponencial (3 tentativas)
• Busca normalizada (insensível a acentos)
• Estatísticas adicionais (máximo, mínimo, média, amplitude)

v1.0.0

• Lançamento inicial
• 6 ferramentas básicas
• Catálogo com 135 séries verificadas

Contribuindo

Contribuições são bem-vindas! Por favor:

1. Faça um fork do repositório
2. Crie um branch de funcionalidade (git checkout -b feature/new-feature)
3. Faça commit das suas alterações (git commit -m 'Add new feature')
4. Envie para o branch (git push origin feature/new-feature)
5. Abra um Pull Request

Licença

Duas licenças, e elas não são a mesma coisa.

• Código: MIT — veja LICENSE.
• Dados: do Banco Central do Brasil, sob a Open Data Commons Open Database License (ODbL) v1.0 — https://opendatacommons.org/licenses/odbl/1-0/. Não é CC0, não é CC BY, não é domínio público: a ODbL exige atribuição, tem uma cláusula de compartilhamento pela mesma licença em bancos de dados derivados e uma cláusula anti-DRM.

Toda resposta bem-sucedida traz um bloco de proveniência com a fonte, a URL da consulta, a data dos dados, o instante real da extração e a licença. Respostas de taxa de câmbio repassam o aviso legal do BCB integralmente, e paridades não-USD são qualificadas como dados de agência de informação (Refinitiv) redistribuídos pelo BCB — não como dados compilados pelo Banco Central.

Detalhes e obrigações em NOTICE.md. Privacidade: nenhum dado do usuário é registrado, por nenhum dos canais — veja PRIVACY.md.

Autor

Sidney da Silva Pereira Bissoli

• GitHub: @SidneyBissoli
• E-mail: sbissoli76@gmail.com

Links Úteis

• Portal SGS do BCB
• Dados Abertos do BCB
• Model Context Protocol
• Registro MCP
• Smithery: bcb-br-mcp
• npm: bcb-br-mcp