{
  "markdown": "# Banco Central do Brasil (BCB) — SGS Time Series MCP Server\n\n[![npm version](https://img.shields.io/npm/v/bcb-br-mcp.svg)](https://www.npmjs.com/package/bcb-br-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/bcb-br-mcp.svg)](https://www.npmjs.com/package/bcb-br-mcp)\n[![node](https://img.shields.io/node/v/bcb-br-mcp)](https://www.npmjs.com/package/bcb-br-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)\n[![LobeHub](https://lobehub.com/badge/mcp/sidneybissoli-bcb-br-mcp)](https://lobehub.com/mcp/sidneybissoli-bcb-br-mcp)\n[![smithery badge](https://smithery.ai/badge/sidneybissoli/bcb-br-mcp)](https://smithery.ai/servers/sidneybissoli/bcb-br-mcp)\n[![GitHub stars](https://img.shields.io/github/stars/SidneyBissoli/bcb-br-mcp?style=flat&logo=github)](https://github.com/SidneyBissoli/bcb-br-mcp)\n[![GitHub Sponsors](https://img.shields.io/github/sponsors/SidneyBissoli?logo=githubsponsors&label=Sponsor&color=db61a2)](https://github.com/sponsors/SidneyBissoli)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![AllMCPs Verified](https://allmcps.com/api/badge/sidneybissoli-bcb-br-mcp)](https://allmcps.com/mcp/sidneybissoli-bcb-br-mcp)\n\n[Leia em Português](README.pt-BR.md)\n\nMCP (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.\n\nQuery economic and financial indicators such as **Selic** (interest rate), **IPCA** (inflation), **exchange rates**, **GDP**, and more, directly from AI assistants like Claude.\n\n> If you find this project useful, please consider giving it a [star on GitHub](https://github.com/SidneyBissoli/bcb-br-mcp). It helps others discover the project!\n\n**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.\n\n## See it in action\n\nAsk your assistant, in plain Portuguese:\n\n- *\"Qual a taxa Selic atual?\"* → `bcb_indicadores_atuais`\n- *\"Mostre o IPCA mês a mês em 2024.\"* → `bcb_serie_valores`\n- *\"Qual foi a variação do dólar nos últimos 12 meses?\"* → `bcb_variacao`\n- *\"O que o mercado espera do IPCA em 2027?\"* → `bcb_focus_expectativas`\n- *\"Qual a Selic esperada na próxima reunião do Copom?\"* → `bcb_focus_selic`\n- *\"Qual foi a PTAX de fechamento do euro na sexta?\"* → `bcb_cambio_cotacao`\n\nThe answers come live from the Brazilian Central Bank's SGS API — exact figures with provenance, not numbers guessed from training data.\n\n## Features\n\n- **Historical data** - Query time series values by code with date filters\n- **Latest values** - Get the most recent N values of any series\n- **Metadata** - Detailed information about series (frequency, source, etc.)\n- **Popular series catalog** - 135 economic indicators verified against the source, organized by category\n- **Smart search** - Find series by keyword (accent-insensitive)\n- **Current indicators** - Latest values for key economic indicators\n- **Long periods, handled** - The BCB API caps daily series at a 10-year window\n  (HTTP 406) and refuses open windows; requests are sliced, fetched and merged\n  automatically, so a 15-year daily query just works\n- **Frequency harmonisation** - Resample a series to monthly, quarterly or annual\n  with an explicit convention, including geometric compounding for series that\n  already are percentage changes (monthly IPCA into annual IPCA)\n- **Variation calculation** - Percentage change between periods with statistics\n- **Series comparison** - Compare multiple series over the same period, with a\n  warning when their periodicities differ\n- **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\n- **PTAX exchange rates** - Official closing quotes for any currency the BCB publishes, single day or date range\n\n📖 **Article (in Portuguese):** [Séries do Banco Central: como consultar o SGS, a Focus e a PTAX sem cair nas armadilhas](docs/artigo-sgs-series-do-banco-central.pt-BR.md) — the three API limits measured live, level vs. rate series, the Focus scopes, and what the ODbL requires. Also published on the site, in Portuguese and English: [sidneybissoli.com](https://sidneybissoli.com/en/blog/posts/series-banco-central/).\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `bcb_serie_valores` | Query series values by code and date range; slices long windows automatically and can harmonise the series to a coarser frequency |\n| `bcb_serie_ultimos` | Get the last N values of a series (any N — the upstream cap of 20 is worked around) |\n| `bcb_serie_metadados` | Get series metadata (name, frequency, category, last value) |\n| `bcb_series_populares` | List popular series grouped by category |\n| `bcb_buscar_serie` | Search series by name or description (accent-insensitive) |\n| `bcb_indicadores_atuais` | Latest values: Selic, IPCA, USD/BRL, IBC-Br |\n| `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 |\n| `bcb_comparar` | Compare 2 to 5 series over the same period with ranking (same level/compounding rule per series, declared in `metodo`) |\n| `bcb_focus_expectativas` | Focus survey expectations for one indicator, horizon as a parameter (monthly, quarterly, annual, rolling 12m/24m inflation); `top5` flag |\n| `bcb_focus_selic` | Focus expectations for the Selic rate, by Copom meeting (R1/2026 form) |\n| `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) |\n| `bcb_cambio_cotacao` | PTAX quote for a currency (USD by default), single day or date range |\n| `bcb_cambio_moedas` | Currencies with quotes published by the BCB |\n| `search` | OpenAI Deep Research contract: searches the series catalog (curated + open data portal index) and returns `{ id, title, url }` — see [ChatGPT (Deep Research)](#chatgpt-deep-research) |\n| `fetch` | OpenAI Deep Research contract: returns one series as a readable document with its canonical public URL |\n\n## Resources\n\nReference catalogs the server exposes as MCP **resources** (read-only contextual data that clients can attach):\n\n| URI | Description |\n|-----|-------------|\n| `bcb://series/populares` | Catalog of 135 verified BCB economic series, organized by category (JSON) |\n| `bcb://series/categorias` | List of available categories in the series catalog (JSON) |\n| `bcb://series/principais` | Codes of the most-used indicators — Selic, IPCA, USD/BRL, GDP, etc. (JSON) |\n\n## Prompts\n\nReady-made templates the server provides as MCP **prompts**:\n\n| Prompt | Description |\n|--------|-------------|\n| `indicadores_atuais` | Query Brazil's key economic indicators (Selic, IPCA, USD/BRL, IBC-Br) |\n| `panorama_economico` | Generate a complete overview of the Brazilian economy |\n| `comparar_inflacao` | Compare Brazil's main inflation indices (IPCA, IGP-M, INPC) over the last 12 months |\n\n## Installation\n\n### Via Smithery (recommended)\n\nVisit [bcb-br-mcp on Smithery](https://smithery.ai/servers/sidneybissoli/bcb-br-mcp) and follow the installation instructions for your MCP client.\n\n### Via URL (Claude.ai, Claude Desktop, any MCP client)\n\nUse the HTTP endpoint directly, no installation required:\n\n```\nhttps://bcb.sidneybissoli.com/mcp\n```\n\nThe legacy hostname `https://bcb.sidneybissoli.workers.dev` keeps working, and so\ndoes the older `POST /` route — clients configured before the endpoint moved to\n`/mcp` are rewritten transparently, so nothing that used to work stopped working.\nNew setups should use the URL above.\n\n### Via npx (Claude Desktop)\n\nAdd to your Claude Desktop configuration file:\n\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"bcb-br\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"bcb-br-mcp\"]\n    }\n  }\n}\n```\n\n### Via global install\n\n```bash\nnpm install -g bcb-br-mcp\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"bcb-br\": {\n      \"command\": \"bcb-br-mcp\"\n    }\n  }\n}\n```\n\n### ChatGPT (Deep Research)\n\nChatGPT 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:\n\n```\nhttps://bcb.sidneybissoli.com/mcp\n```\n\n`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.\n\n## Usage Examples\n\n### Get the current Selic rate\n\n```\nWhat is the current Selic interest rate?\n→ Uses bcb_indicadores_atuais\n```\n\n### IPCA history for 2024\n\n```\nShow me the monthly IPCA for 2024\n→ Uses bcb_serie_valores with code 433, dataInicial 2024-01-01, dataFinal 2024-12-31\n```\n\n### List inflation indicators\n\n```\nWhat inflation series are available?\n→ Uses bcb_series_populares with category \"Inflação\"\n```\n\n### Search for USD exchange rate series\n\n```\nSearch for series related to the dollar\n→ Uses bcb_buscar_serie with term \"dolar\" (works without accents)\n```\n\n### Calculate USD/BRL variation\n\n```\nWhat was the USD/BRL variation over the last 12 months?\n→ Uses bcb_variacao with code 1 and periodos 12\n```\n\n### Compare IPCA, IGP-M, and INPC\n\n```\nCompare IPCA, IGP-M, and INPC in 2024\n→ Uses bcb_comparar with codes [433, 189, 188], dataInicial 2024-01-01, dataFinal 2024-12-31\n```\n\n## Series Catalog (135)\n\nThe curated catalog holds **135 series, each verified against the source** on 2026-08-13 (4 discontinued FGV series were removed on 2026-08-23).\n\nThe `fonteNome` field on every entry says where its name comes from:\n\n- **`portal`** (82 series) — the name is transcribed from the series' dataset on the\n  BCB Open Data Portal, and `unidade` carries the published unit of measure.\n- **`medido`** (53 series) — the series has no dataset on the portal, so the name is\n  inherited; what was verified against the source is its periodicity and order of magnitude.\n\nPeriodicity is always the **measured** one (from the spacing between observations), never an\ninherited label. Market expectations are **not** here — use `bcb_focus_expectativas`.\n\n### Juros (14)\n\n| Code | Name | Periodicity | Name source |\n|------|------|-------------|-------------|\n| 11 | Taxa de juros - Selic | Diária | `portal` |\n| 432 | Taxa de juros - Meta Selic definida pelo Copom | Diária | `portal` |\n| 1178 | Taxa de juros - Selic anualizada base 252 | Diária | `portal` |\n| 4189 | Taxa de juros - Selic acumulada no mês anualizada base 252 | Mensal | `portal` |\n| 4390 | Taxa de juros - Selic acumulada no mês | Mensal | `portal` |\n| 12 | Taxa de juros - CDI diária | Diária | `medido` |\n| 4389 | Taxa de juros - CDI anualizada base 252 | Diária | `medido` |\n| 4391 | Taxa de juros - CDI acumulada no mês | Mensal | `medido` |\n| 4392 | Taxa de juros - CDI acumulada no mês anualizada | Mensal | `medido` |\n| 226 | Taxa Referencial (TR) - diária | Diária | `medido` |\n| 7811 | Taxa Referencial (TR) - mensal | Mensal | `medido` |\n| 7812 | Taxa Referencial (TR) - anualizada | Mensal | `medido` |\n| 256 | Taxa de Juros de Longo Prazo (TJLP) | Mensal | `medido` |\n| 253 | Taxa de juros - CDB pré-fixado - 30 dias | Diária | `medido` |\n\n### Inflação (28)\n\n| Code | Name | Periodicity | Name source |\n|------|------|-------------|-------------|\n| 433 | IPCA - Variação mensal | Mensal | `medido` |\n| 13522 | IPCA - Variação acumulada em 12 meses | Mensal | `medido` |\n| 7478 | IPCA-15 - Variação mensal | Mensal | `medido` |\n| 10764 | IPCA-E - Variação mensal | Mensal | `medido` |\n| 16121 | Índice nacional de preços ao consumidor - Amplo (IPCA) - Núcleo por exclusão - ex2 | Mensal | `portal` |\n| 16122 | Índice nacional de preços ao consumidor - Amplo (IPCA) - Núcleo de dupla ponderação | Mensal | `portal` |\n| 11426 | Índice nacional de preços ao consumidor - Amplo (IPCA) - Núcleo médias aparadas sem suavização | Mensal | `portal` |\n| 11427 | Índice nacional de preços ao consumidor - Amplo (IPCA) - Núcleo por exclusão - Sem monitorados e alimentos no domicílio | Mensal | `portal` |\n| 10841 | Índice de Preços ao Consumidor-Amplo (IPCA) - Bens não-duráveis | Mensal | `portal` |\n| 10842 | Índice de Preços ao Consumidor-Amplo (IPCA) - Bens semi-duráveis | Mensal | `portal` |\n| 10843 | Índice de Preços ao Consumidor-Amplo (IPCA) - Duráveis | Mensal | `portal` |\n| 10844 | Índice de Preços ao Consumidor-Amplo (IPCA) - Serviços | Mensal | `portal` |\n| 4449 | Índice nacional de preços ao consumidor-Amplo (IPCA) - Preços monitorados - Total | Mensal | `portal` |\n| 11428 | Índice nacional de preços ao consumidor - Amplo (IPCA) - Itens livres | Mensal | `portal` |\n| 188 | INPC - Variação mensal | Mensal | `medido` |\n| 189 | IGP-M - Variação mensal | Mensal | `medido` |\n| 7447 | IGP-10 - Variação mensal | Mensal | `medido` |\n| 7448 | IGP-M - 1ª prévia | Mensal | `medido` |\n| 7449 | IGP-M - 2ª prévia | Mensal | `medido` |\n| 190 | IGP-DI - Variação mensal | Mensal | `medido` |\n| 7450 | IPA-M - Variação mensal | Mensal | `medido` |\n| 225 | IPA-DI - Geral - Variação mensal | Mensal | `medido` |\n| 7459 | IPA-DI - Produtos industriais | Mensal | `medido` |\n| 7460 | IPA-DI - Produtos agrícolas | Mensal | `medido` |\n| 191 | IPC-DI - Variação mensal | Mensal | `medido` |\n| 193 | IPC-Fipe - Variação mensal | Mensal | `medido` |\n| 17679 | IPC-3i - Variação mensal | Mensal | `medido` |\n| 17680 | IPC-C1 - Variação mensal | Mensal | `medido` |\n\n### Câmbio (13)\n\n| Code | Name | Periodicity | Name source |\n|------|------|-------------|-------------|\n| 1 | Taxa de câmbio - Livre - Dólar americano (venda) - diário | Diária | `portal` |\n| 10813 | Taxa de câmbio - Livre - Dólar americano (compra) | Diária | `portal` |\n| 3698 | Taxa de câmbio - PTAX - Dólar americano (venda) | Mensal | `medido` |\n| 3697 | Taxa de câmbio - PTAX - Dólar americano (compra) | Mensal | `medido` |\n| 3695 | Taxa de câmbio - PTAX - Dólar americano (média) | Mensal | `medido` |\n| 21619 | Taxa de câmbio - Euro (venda) | Diária | `medido` |\n| 21620 | Taxa de câmbio - Euro (compra) | Diária | `medido` |\n| 21623 | Taxa de câmbio - Libra Esterlina (venda) | Diária | `medido` |\n| 21624 | Taxa de câmbio - Libra Esterlina (compra) | Diária | `medido` |\n| 21621 | Taxa de câmbio - Iene (venda) | Diária | `medido` |\n| 21622 | Taxa de câmbio - Iene (compra) | Diária | `medido` |\n| 21625 | Taxa de câmbio - Franco Suíço (venda) | Diária | `medido` |\n| 21626 | Taxa de câmbio - Franco Suíço (compra) | Diária | `medido` |\n\n### Atividade Econômica (21)\n\n| Code | Name | Periodicity | Name source |\n|------|------|-------------|-------------|\n| 4380 | PIB mensal - Valores correntes (R$ milhões) | Mensal | `medido` |\n| 4381 | PIB acumulado no ano - Valores correntes (R$ milhões) | Mensal | `medido` |\n| 4382 | PIB acumulado dos últimos 12 meses - Valores correntes (R$ milhões) | Mensal | `medido` |\n| 4385 | PIB mensal em US$ (milhões) | Mensal | `medido` |\n| 4386 | PIB acumulado no ano em US$ (milhões) | Mensal | `medido` |\n| 7324 | PIB anual em US$ (milhões) | Anual | `medido` |\n| 24363 | Índice de Atividade Econômica do Banco Central - IBC-Br | Mensal | `portal` |\n| 24364 | Índice de Atividade Econômica do Banco Central (IBC-Br) - com ajuste sazonal | Mensal | `portal` |\n| 29601 | Índice de Atividade Econômica do Banco Central (IBC-Br) Agropecuária | Mensal | `portal` |\n| 29602 | Índice de Atividade Econômica do Banco Central (IBC-Br) Agropecuária - com ajuste sazonal | Mensal | `portal` |\n| 29603 | Índice de Atividade Econômica do Banco Central (IBC-Br) Indústria | Mensal | `portal` |\n| 29604 | Índice de Atividade Econômica do Banco Central (IBC-Br) Indústria - com ajuste sazonal | Mensal | `portal` |\n| 29605 | Índice de Atividade Econômica do Banco Central (IBC-Br) Serviços | Mensal | `portal` |\n| 29606 | Índice de Atividade Econômica do Banco Central (IBC-Br) Serviços - com ajuste sazonal | Mensal | `portal` |\n| 22103 | Exportação de bens e serviços - Trimestral | Trimestral | `medido` |\n| 22104 | Importação de bens e serviços - Trimestral | Trimestral | `medido` |\n| 22109 | Consumo das famílias - Trimestral | Trimestral | `medido` |\n| 22110 | Consumo do governo - Trimestral | Trimestral | `medido` |\n| 22111 | Formação bruta de capital fixo - Trimestral | Trimestral | `medido` |\n| 21859 | Produção industrial - Geral - Variação mensal | Mensal | `medido` |\n| 21862 | Utilização da capacidade instalada - Indústria | Mensal | `medido` |\n\n### Emprego (4)\n\n| Code | Name | Periodicity | Name source |\n|------|------|-------------|-------------|\n| 24369 | Taxa de desocupação - PNAD Contínua | Mensal | `medido` |\n| 24380 | Rendimento médio real habitual - Todos os trabalhos | Mensal | `medido` |\n| 24381 | Massa de rendimento real habitual | Mensal | `medido` |\n| 28561 | CAGED - Saldo de empregos formais | Mensal | `medido` |\n\n### Fiscal (7)\n\n| Code | Name | Periodicity | Name source |\n|------|------|-------------|-------------|\n| 4503 | Dívida Líquida do Setor Público (% PIB) - Total - Governo Federal e Banco Central | Mensal | `portal` |\n| 4513 | Dívida Líquida do Setor Público (% PIB) - Total - Setor público consolidado | Mensal | `portal` |\n| 4505 | Dívida Líquida do Setor Público (% PIB) - Total - Banco Central | Mensal | `portal` |\n| 4536 | Dívida líquida do governo geral (% PIB) | Mensal | `portal` |\n| 4537 | Dívida bruta do governo geral (% PIB) - Metodologia utilizada até 2007 | Mensal | `portal` |\n| 5364 | Receita total do governo central | Mensal | `medido` |\n| 5793 | NFSP sem desvalorização cambial (% PIB) - Fluxo acumulado em 12 meses - Resultado primário - Total - Setor público consolidado | Mensal | `portal` |\n\n### Setor Externo (12)\n\n| Code | Name | Periodicity | Name source |\n|------|------|-------------|-------------|\n| 3546 | Reservas internacionais - Conceito liquidez - Total | Mensal | `medido` |\n| 13621 | Reservas internacionais - Conceito caixa - Total - diária | Diária | `portal` |\n| 22707 | Balança comercial - Balanço de Pagamentos - mensal - saldo | Mensal | `portal` |\n| 22708 | Exportação de bens - Balanço de Pagamentos - mensal | Mensal | `portal` |\n| 22709 | Importação de bens - Balanço de Pagamentos - mensal | Mensal | `portal` |\n| 22714 | Bens exportados sob merchanting - exportações positivas - mensal | Mensal | `portal` |\n| 22701 | Transações correntes - mensal - saldo | Mensal | `portal` |\n| 22704 | Balança comercial e Serviços - mensal - saldo | Mensal | `portal` |\n| 22715 | Bens importados sob merchanting - exportações negativas - mensal | Mensal | `portal` |\n| 22716 | Balança comercial - ouro não monetário - Balanço de Pagamentos - mensal - saldo | Mensal | `portal` |\n| 22846 | Renda secundária - Demais setores - Transferências pessoais - mensal - receita | Mensal | `portal` |\n| 22885 | Investimentos diretos no país - IDP - mensal - líquido | Mensal | `portal` |\n\n### Crédito (30)\n\n| Code | Name | Periodicity | Name source |\n|------|------|-------------|-------------|\n| 20539 | Saldo da carteira de crédito - Total | Mensal | `portal` |\n| 20540 | Saldo da carteira de crédito - Pessoas jurídicas - Total | Mensal | `portal` |\n| 20541 | Saldo da carteira de crédito - Pessoas físicas - Total | Mensal | `portal` |\n| 20542 | Saldo da carteira de crédito com recursos livres - Total | Mensal | `portal` |\n| 20570 | Saldo da carteira de crédito com recursos livres - Pessoas físicas - Total | Mensal | `portal` |\n| 20592 | Saldo da carteira de crédito com recursos livres - Pessoas físicas - Outros créditos livres | Mensal | `portal` |\n| 20615 | Saldo da carteira de crédito com recursos direcionados - Pessoas físicas - Financiamento agroindustrial com recursos do BNDES | Mensal | `portal` |\n| 20631 | Concessões de crédito - Total | Mensal | `portal` |\n| 20665 | Concessões de crédito com recursos livres - Pessoas físicas - Cheque especial | Mensal | `portal` |\n| 20714 | Taxa média de juros das operações de crédito - Total | Mensal | `portal` |\n| 20716 | Taxa média de juros das operações de crédito - Pessoas físicas - Total | Mensal | `portal` |\n| 20740 | Taxa média de juros das operações de crédito com recursos livres - Pessoas físicas - Total | Mensal | `portal` |\n| 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` |\n| 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` |\n| 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` |\n| 20783 | Spread médio das operações de crédito - Total | Mensal | `portal` |\n| 20785 | Spread médio das operações de crédito - Pessoas físicas - Total | Mensal | `portal` |\n| 20786 | Spread médio das operações de crédito com recursos livres - Total | Mensal | `portal` |\n| 21082 | Inadimplência da carteira de crédito - Total | Mensal | `portal` |\n| 21084 | Inadimplência da carteira de crédito - Pessoas físicas - Total | Mensal | `portal` |\n| 21085 | Inadimplência da carteira de crédito com recursos livres - Total | Mensal | `portal` |\n| 21128 | Inadimplência da carteira de crédito com recursos livres - Pessoas físicas - Cartão de crédito parcelado | Mensal | `portal` |\n| 21129 | Inadimplência da carteira de crédito com recursos livres - Pessoas físicas - Cartão de crédito total | Mensal | `portal` |\n| 13685 | Inadimplência da carteira de crédito das instituições financeiras sob controle privado - Total | Mensal | `portal` |\n| 29033 | Comprometimento de renda das famílias com juros da dívida com o Sistema Financeiro Nacional - Com ajuste sazonal (RNDBF) | Mensal | `portal` |\n| 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` |\n| 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` |\n| 29036 | Comprometimento de renda das famílias com amortização da dívida com o Sistema Financeiro Nacional - Com ajuste sazonal (RNDBF) | Mensal | `portal` |\n| 29037 | Endividamento das famílias com o Sistema Financeiro Nacional em relação à renda acumulada dos últimos doze meses (RNDBF) | Mensal | `portal` |\n| 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` |\n\n### Agregados Monetários (8)\n\n| Code | Name | Periodicity | Name source |\n|------|------|-------------|-------------|\n| 1788 | BM - Base monetária restrita (saldo em final de período) | Mensal | `portal` |\n| 1833 | Base Monetária Ampliada (saldo em final de período) | Mensal | `portal` |\n| 27788 | Meios de pagamento - M1 (média dos dias úteis do mês) - Novo | Mensal | `portal` |\n| 27789 | Meios de pagamento - Papel moeda em poder do público (saldo em final de período) - Novo | Mensal | `portal` |\n| 27790 | Meios de pagamento - Depósitos à vista (saldo em final de período) - Novo | Mensal | `portal` |\n| 27791 | Meios de pagamento - M1 (saldo em final de período) - Novo | Mensal | `portal` |\n| 27815 | Meios de pagamento amplos - M4 (saldo em final de periodo) - Novo | Mensal | `portal` |\n| 7530 | Comportamento monetário - Comportamento do público - C | Mensal | `portal` |\n\n### Poupança (2)\n\n| Code | Name | Periodicity | Name source |\n|------|------|-------------|-------------|\n| 25 | Depósitos de poupança até 03.05.2012 - Rentabilidade no período | Diária | `portal` |\n| 195 | Depósitos de poupança a partir de 04.05.2012 - Rentabilidade no período | Diária | `portal` |\n\n\nThe full machine-readable catalog is served as the `bcb://series/populares` resource and by\n`bcb_series_populares`. Thousands of further series are reachable through `bcb_buscar_serie`,\nwhich also queries the BCB Open Data Portal index.\n\n## Finding Other Series\n\nThe SGS database contains over 18,000 time series. To find codes for other series:\n\n1. Visit the [BCB SGS Portal](https://www3.bcb.gov.br/sgspub/)\n2. Search for the desired series\n3. Note the series code\n4. Use that code with this server's tools\n\n## Technical Details\n\n### Robustness\n\n- **Timeout**: 30 seconds per request (prevents hanging)\n- **Auto-retry**: 3 attempts with exponential backoff (1s, 2s, 4s) for transient\n  failures; client errors (4xx) are not retried, since they are deterministic\n- **Error handling**: Clear error messages\n\n### Working around the SGS limits\n\nMeasured against the live API, not inferred from documentation:\n\n- A **date window over 10 years on a daily series** is refused with HTTP **406**,\n  and so is an open window (no `dataInicial`, or no dates at all). The limit\n  applies to the *implicit* window: with no `dataFinal` the API assumes today.\n  Requests are sliced into windows of up to **3 years**, fetched with bounded\n  concurrency and merged in date order without duplicating the seams; the response\n  reports it in `chunking`. The slice is 3 years rather than the allowed 10 because\n  a 10-year daily window costs 10–20 s upstream and may be cut off around 30 s.\n- **`dados/ultimos/N` is capped at 20** by the API, in every periodicity. Above 20,\n  the server infers the series' periodicity and fetches by date window instead.\n- **There is no per-series metadata endpoint** (`/metadados` answers 404). Frequency\n  is inferred from the spacing of the observations and flagged with\n  `periodicidadeInferida`; unit of measure is not available from any source.\n\n### Derived values\n\nAnything this server computes — variation, descriptive statistics, harmonised\nseries — is marked `derived: true` and carries a note with the conventions used.\nStatistics come from [`@sbissoli/mcp-stats`](https://www.npmjs.com/package/@sbissoli/mcp-stats).\nA value published by the BCB is always returned verbatim; only computed values are\nrounded (to 4 decimals).\n\n### Smart Search\n\n`bcb_buscar_serie` searches two layers: the curated catalog of 135 verified series (which ranks first, with\nthe source of the name declared) and the index of the BCB Open Data Portal, with thousands of series\nidentified by code. Terms are accent- and case-insensitive, and several terms are combined with AND:\n\n- `\"inflacao\"` → finds \"Inflação\"\n- `\"cambio\"` → finds \"Câmbio\"\n- `\"ipca servicos\"` → both terms must match\n\nThe portal index is served from a 24-hour cache, renewed by the first search after it expires (one request to\nthe portal, only metadata — series codes and names, never observations). Every answer carries\n`catalogo.cobertura`: the index is **not** the whole SGS, so not finding a series here is not proof it does not\nexist.\n\n### Data source and licence\n\nData obtained from the Banco Central do Brasil (SGS / Olinda-Expectativas / PTAX), published under the\n**Open Data Commons Open Database License (ODbL) v1.0** — https://opendatacommons.org/licenses/odbl/1-0/.\nRe-verified against the source on 2026-08-13: 4,259 of the portal's 4,260 datasets declare\n`license_id: \"odc-odbl\"`. This is **not** CC0, CC BY, or public domain — ODbL carries attribution,\nshare-alike (on derived databases) and anti-DRM clauses. Exchange-rate answers pass through the BCB's own\nliability disclaimer verbatim; cross-currency parities are **not** compiled by the BCB — they come from an\ninformation agency (Refinitiv) and are redistributed by the BCB, and the tools say so.\n\nThe server's own code is MIT; the data is not. See [NOTICE.md](NOTICE.md). Privacy: no user data is logged, by either channel — see [PRIVACY.md](PRIVACY.md).\n\n### Provenance block\n\nEvery successful tool response carries a provenance block (portfolio contract v1.0) in two channels:\n`structuredContent.provenance` + `attribution` (visible to the model) and a `_meta` mirror under\n`br.com.sidneybissoli.bcb/*` (out of band, zero tokens). Each block names the source, the canonical URL that\nreproduces the query, the data vintage, the **real** upstream extraction instant, and the licence.\n\nTwo details that are easy to get wrong and are handled here:\n\n- **`retrieved_at` is the real extraction instant, not \"now\".** The portal index is served from a 24-hour\n  cache, so a search answered from cache reports the instant the index was actually fetched — which can be a\n  day old, and is the legally relevant date.\n- **One block per provenance, never merged.** `bcb_buscar_serie` separates the BCB portal index from the\n  server's own curated catalogue; `bcb_serie_metadados` separates the live SGS reading from the catalogue;\n  `bcb_cambio_cotacao` separates BCB-compiled dollar rates from agency-sourced cross-currency parities.\n\n## Development\n\n### Requirements\n\n- Node.js >= 18.0.0\n\n### Setup\n\n```bash\ngit clone https://github.com/SidneyBissoli/bcb-br-mcp.git\ncd bcb-br-mcp\nnpm install\n```\n\n### Build\n\n```bash\nnpm run build\n```\n\n### Local testing (stdio)\n\n```bash\nnpm run dev\n```\n\n### Local testing (HTTP worker)\n\n```bash\nnpm run dev:worker\n```\n\nOr use the MCP Inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector npm run dev\n```\n\n## BCB API\n\nThis server uses the Brazilian Central Bank's public API:\n\n- **Base endpoint:** `https://api.bcb.gov.br/dados/serie/bcdata.sgs.{code}/dados`\n- **Format:** JSON\n- **Authentication:** None (public API)\n- **Documentation:** [BCB Open Data](https://dadosabertos.bcb.gov.br/)\n\n## Changelog\n\n### v1.4.1\n\n- `bcb_focus_referencias`: the parameter is now `escopo`, not `horizonte`, and the\n  response array is `escopos`. The scopes are the five horizons of\n  `bcb_focus_expectativas` **plus `selic`** — and `selic` is not a horizon: its\n  axis is the Copom meeting. Each block names the `tool` that consumes it. The\n  previous name implied `selic` was a queryable horizon of\n  `bcb_focus_expectativas`, which it is not. Never published to npm under the old\n  name.\n\n### v1.4.0\n\n- **Three APIs under one contract, 8 tools → 13.** Focus market-expectations\n  survey (`bcb_focus_expectativas`, `bcb_focus_selic`, `bcb_focus_referencias`)\n  and PTAX exchange rates (`bcb_cambio_cotacao`, `bcb_cambio_moedas`), consolidated\n  by parameter rather than mirroring the source's ~18 OData resources.\n- **Real search.** `bcb_buscar_serie` now queries the Open Data Portal index\n  (3,500+ series, 24-hour cache, metadata only) on top of the curated catalog, and\n  states the index's coverage instead of claiming a series does not exist.\n- Every Focus and PTAX field name verified against the live API, including the\n  Top 5 Selic resource, which publishes its fields in a different case from the\n  other twelve.\n- ODbL obligations shipped with the exchange-rate tools: the BCB disclaimer is\n  passed through verbatim, and non-USD parities are qualified as third-party\n  (Refinitiv) data redistributed by the BCB.\n\n### v1.2.0\n\n- HTTP endpoint via Cloudflare Workers (`https://bcb.sidneybissoli.workers.dev`)\n- Published on Smithery.ai\n- Refactored: tool logic extracted to `src/tools.ts` (shared between stdio and HTTP)\n\n### v1.1.0\n\n- New tool `bcb_variacao` for percentage variation calculation\n- New tool `bcb_comparar` for comparing multiple series\n- 30-second timeout on requests\n- Auto-retry with exponential backoff (3 attempts)\n- Normalized search (accent-insensitive)\n- Additional statistics (max, min, average, range)\n\n### v1.0.0\n\n- Initial release\n- 6 basic tools\n- Catalog with 135 verified series\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/new-feature`)\n3. Commit your changes (`git commit -m 'Add new feature'`)\n4. Push to the branch (`git push origin feature/new-feature`)\n5. Open a Pull Request\n\n## License\n\n**Two licences, and they are not the same thing.**\n\n- **Code:** MIT — see [LICENSE](LICENSE).\n- **Data:** from the Banco Central do Brasil, under the **Open Data Commons Open\n  Database License (ODbL) v1.0** — https://opendatacommons.org/licenses/odbl/1-0/.\n  Not CC0, not CC BY, not public domain: the ODbL requires **attribution**, has a\n  **share-alike** clause on derived databases, and an **anti-DRM** clause.\n\nEvery successful response carries a provenance block with the source, the query URL, the data vintage, the\nreal extraction instant and the licence. Exchange-rate answers pass the BCB disclaimer through verbatim, and\nnon-USD parities are qualified as information-agency data (Refinitiv) redistributed by the BCB — not as data\ncompiled by the Central Bank.\n\nDetails and obligations in [NOTICE.md](NOTICE.md). Privacy: no user data is logged, by either channel — see [PRIVACY.md](PRIVACY.md).\n\n## Author\n\n**Sidney da Silva Pereira Bissoli**\n\n- GitHub: [@SidneyBissoli](https://github.com/SidneyBissoli)\n- Email: sbissoli76@gmail.com\n\n## Useful Links\n\n- [BCB SGS Portal](https://www3.bcb.gov.br/sgspub/)\n- [BCB Open Data](https://dadosabertos.bcb.gov.br/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [MCP Registry](https://registry.modelcontextprotocol.io/)\n- [Smithery: bcb-br-mcp](https://smithery.ai/servers/sidneybissoli/bcb-br-mcp)\n- [npm: bcb-br-mcp](https://www.npmjs.com/package/bcb-br-mcp)\n",
  "bytes": 34356,
  "sha": "a0618a31d3a90d33abb7724f9367b66afe56364444155f7ad2bd22f2f8e04dd5",
  "repo_slug": "sidneybissoli/bcb-br-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sidneybissoli_bcb_br_mcp_d344b059/readme"
}