bcb-br-mcp

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

[![npm version](https://img.shields.io/npm/v/bcb-br-mcp.svg)](https://www.npmjs.com/package/bcb-br-mcp)
[![npm downloads](https://img.shields.io/npm/dm/bcb-br-mcp.svg)](https://www.npmjs.com/package/bcb-br-mcp)
[![node](https://img.shields.io/node/v/bcb-br-mcp)](https://www.npmjs.com/package/bcb-br-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)
[![LobeHub](https://lobehub.com/badge/mcp/sidneybissoli-bcb-br-mcp)](https://lobehub.com/mcp/sidneybissoli-bcb-br-mcp)
[![smithery badge](https://smithery.ai/badge/sidneybissoli/bcb-br-mcp)](https://smithery.ai/servers/sidneybissoli/bcb-br-mcp)
[![GitHub stars](https://img.shields.io/github/stars/SidneyBissoli/bcb-br-mcp?style=flat&logo=github)](https://github.com/SidneyBissoli/bcb-br-mcp)
[![GitHub Sponsors](https://img.shields.io/github/sponsors/SidneyBissoli?logo=githubsponsors&label=Sponsor&color=db61a2)](https://github.com/sponsors/SidneyBissoli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![AllMCPs Verified](https://allmcps.com/api/badge/sidneybissoli-bcb-br-mcp)](https://allmcps.com/mcp/sidneybissoli-bcb-br-mcp)
[![mcpindex](https://mcpindex.ai/api/v1/badge/io-github-sidneybissoli-bcb-br-mcp)](https://mcpindex.ai/server/io-github-sidneybissoli-bcb-br-mcp)

[Leia em Português](LEIA-ME.md)

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](https://github.com/SidneyBissoli/bcb-br-mcp). 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](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/).

## Available Tools

| Tool | Description |
|------|-------------|
| `bcb_serie_valores` | 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)](#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**:

| Prompt | Description |
|--------|-------------|
| `indicadores_atuais` | Query Brazil's key economic indicators (Selic, IPCA, USD/BRL, IBC-Br) |
| `panorama_economico` | 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](https://smithery.ai/servers/sidneybissoli/bcb-br-mcp) 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`

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

### Via global install

```bash
npm install -g bcb-br-mcp
```

```json
{
  "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 th