Banco Central Do Brasil (BCB) — SGS Time Series MCP Server

Banco Central do Brasil (BCB) — SGS Time Series MCP Server

Leia em Português

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

📖 Article (in Portuguese): Séries do Banco Central: como consultar o SGS, a Focus e a PTAX sem cair nas armadilhas — 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.

Available Tools

Resources

Reference catalogs the server exposes as MCP resources (read-only contextual data that clients can attach):

Prompts

Ready-made templates the server provides as MCP prompts:

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:

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.

Via npx (Claude Desktop)

Add to your Claude Desktop configuration file:

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 global install

npm install -g bcb-br-mcp

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

ChatGPT (Deep Research)

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:

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

What is the current Selic interest rate?
→ Uses bcb_indicadores_atuais

IPCA history for 2024

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

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

Search for USD exchange rate series

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

Calculate USD/BRL variation

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

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)

Inflação (28)

Câmbio (13)

Atividade Econômica (21)

Emprego (4)

Fiscal (7)

Setor Externo (12)

Crédito (30)

Agregados Monetários (8)

Poupança (2)

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:

1. Visit the BCB SGS Portal
2. Search for the desired series
3. Note the series code
4. Use that code with this server's tools

Ask in your words, not the BCB's

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.

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.

Three 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.
• What each number is, and which version of it. An SGS observation is only {data, valor}: the date of a monthly, quarterly or annual series is the first day of the reference period, and some series arrive already accumulated (year-to-date GDP 4381/4386; 12-month IPCA 13522, GDP 4382, primary balance 5793), which only their name tells. The tool descriptions say so, and data_vintage is the span actually covered — including on the four tools that compute across several series. Every value is the version the SGS publishes at retrieved_at: the BCB revises series such as GDP and IBC-Br and the SGS keeps no as-first-published copy, so this server cannot return one.

Development

Surface fingerprint, checkable from the registry

Every release publishes, in its MCP Registry entry, the sha256 of the surface this version serves (initialize, tools, resources, prompts) and which methods answer without a credential. A surface change without a version bump fails the build; the fingerprint in the registry lets a client check the same thing on its own side. Canonical form and procedure: SPEC.md of @sbissoli/mcp-surface. To check it yourself (Node 18+, no dependencies):

curl -sO https://raw.githubusercontent.com/SidneyBissoli/mcp-br-commons/main/packages/mcp-surface/exemplos/verify.mjs
node verify.mjs io.github.SidneyBissoli/bcb-br-mcp

Requirements

• Node.js >= 18.0.0

Setup

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

Build

npm run build

Local testing (stdio)

npm run dev

Local testing (HTTP worker)

npm run dev:worker

Or use the MCP Inspector:

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
• Format: JSON
• Authentication: None (public API)
• Documentation: BCB Open Data

Changelog

v1.4.1

• 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_expectativas plus 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:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-feature)
3. Commit your changes (git commit -m 'Add new feature')
4. Push to the branch (git push origin feature/new-feature)
5. Open a Pull Request

License

Two licences, and they are not the same thing.

• Code: MIT — see LICENSE.
• 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.

Author

Sidney da Silva Pereira Bissoli

• GitHub: @SidneyBissoli
• Email: [email protected]

Useful Links

• BCB SGS Portal
• BCB Open Data
• Model Context Protocol
• MCP Registry
• Smithery: bcb-br-mcp
• npm: bcb-br-mcp