bcb-br-mcp

# Brazilian Central Bank (BCB) - MCP

[![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)

[Leia em Português](README.pt-BR.md)

MCP (Model Context Protocol) server for the **Brazilian Central Bank** (Banco Central do Brasil, **BCB**) time series data (SGS/BCB).

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:** 15 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

## 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) |
| `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 |

## 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"
    }
  }
}
```

## 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`** (57 series) — the series has no dataset on the portal, so the name is
  inherited; what was verified against the source is its periodicity and order of magnitude.

Periodicity is always the **measured** one (from the spacing between observations), never an
inherited label. Market expectations are **not** here — use `bcb_focus_expectativas`.

### Juros (14)

| Code | Name | Periodicity | Name source |
|------|------|-------------|-------------|
| 11 | Taxa de juros - Selic | Diária | `portal` |
| 432 | Taxa de juros - Meta Selic definida pelo Copom | Diária | `portal` |
| 1178 | Taxa de juros - Selic anualizada base 252 | Diária | `portal` |
| 4189 | Taxa de juros - Selic acumulada no mês anualizada base 252 | Mensal | `portal` |
| 4390 | Taxa de juros - Selic acumulada no mês | Mensal | `portal` |
| 12 | Taxa de juros - CDI diária | Diária | `medido` |
| 4389 | Taxa de juros - CDI anualizada base 252 |