dados-b3-mcp

# Dados B3 — MCP server (Brazilian stock market, auditable fundamentals)

*[Português abaixo](#dados-b3--servidor-mcp-bolsa-brasileira-fundamentos-auditáveis)*

An [MCP](https://modelcontextprotocol.io) connector that gives your AI agent
(Claude, ChatGPT, Cursor and others) access to **fundamentals for Brazilian
listed companies (B3) — banks and insurers included — from 2010 to today**,
with a **fully published methodology**: ROE, ROIC, margins, growth, net
debt/EBITDA, **point-in-time multiples** (P/E, P/B, EV/EBITDA priced at the
first trading session *on or after* the day the filing actually became
public — no look-ahead, usable for backtests), **dividends and dividend yield**,
**ready-made scores (Piotroski F-Score and Graham)** and a **record of restated
filings**.

Sources: CVM open data (ODbL) and B3 (COTAHIST). Every figure carries the CVM
account it came from, and **nothing is published unless a suite of invariant
tests passes** — the balance sheet balances, the income statement reconciles,
and a price never precedes the filing that justifies it.

Product and plans: **https://dadosb3.com/?de=github**

## Use 1 — remote (nothing to install, recommended)

Add this remote connector to your AI client:

```
https://dadosb3.com/mcp/
```

In Claude: Settings → Connectors → add custom connector → paste the URL.

## Use 2 — local (stdio)

```bash
pip install -r requirements.txt
python server.py
```

```json
{
  "mcpServers": {
    "dados-b3": {
      "command": "python",
      "args": ["server.py"],
      "env": { "DADOS_B3_API_KEY": "your_optional_key" }
    }
  }
}
```

## Use 3 — Docker image (one command, no local Python)

```bash
docker run -i --rm -e DADOS_B3_API_KEY=your_optional_key ghcr.io/val7h/dados-b3-mcp:latest
```

```json
{
  "mcpServers": {
    "dados-b3": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/val7h/dados-b3-mcp:latest"]
    }
  }
}
```

The image is published on every push to `main`
(`.github/workflows/publicar-imagem.yml`). It exists for two reasons: a
one-command install path, and letting MCP directories actually run the server
in order to evaluate it.

## Tools

| Tool | What it does | Free? |
|---|---|---|
| `listar_empresas` | Every covered company (name, tax ID, ticker), banks and insurers included | yes |
| `indicadores_anuais` | ROE, ROIC, margins, growth, net debt/EBITDA — annual series from 2010 | WEGE3 yes; others need a key |
| `multiplos` | P/E, P/B, EV/EBITDA point-in-time; trailing P/E | WEGE3 yes; others need a key |
| `fatos_contabeis` | Standardised accounts carrying the CVM code each figure came from | WEGE3 yes; others need a key |
| `dividendos` | Cash distributions, annual summary and 12-month dividend yield | WEGE3 yes; others need a key |
| `scores` | Piotroski F-Score with all nine criteria shown, plus the Graham test | WEGE3 yes; others need a key |
| `reapresentacoes` | Restated filings — the original and the revised figure side by side | WEGE3 yes; others need a key |
| `trimestres` | Quarterly series: Q1/Q2/Q3 accounts as filed, the quarter's price, margins and trailing ROE | WEGE3 yes; others need a key |
| `etfs_ranking` | B3 ETFs: most traded, largest net assets, largest premium/discount to same-day NAV, 12m NAV return, lowest EFFECTIVE fee | yes |
| `etf` | One ETF: daily NAV (FNET filing), premium/discount, monthly effective fee, portfolio (CDA) and overlap with peers | BOVA11 yes; others need a key |
| `auditar_amostra` | Draws cases with YOUR seed so you can recompute each figure against the CVM file (formula, account, where to look) | yes |
| `fiis_ranking` | Most discounted FIIs (point-in-time P/B), highest 12m yield and medians by segment | needs a key |
| `hoje` | What changed in the last 30 days: filings published, filings **re-sent**, dividends, fund distributions, corporate actions, ticker changes | yes |
| `fii` | One real-estate fund: point-in-time P/B, 12-month yield, vacancy, recent distributions | MXRF11 yes; others need a key |
| `fiis` | Filters funds by P/B and dividend-yield ranges | key required |
| `screener` | Filters the whole market by indicator ranges; `as_of` answers what was PUBLIC on a date (no look-ahead); `recibo=True` freezes the answer at a permanent, citable address | key required |
| `recibo` | Reads a frozen screener query: question, cut-off date, data version, result and its sha256 | yes |
| `veredito` | Descriptive summary of one stock: six numbers in three questions, each with its numeric band and comparison (sector median, the company's own history, the whole market), plus the data confidence flag — facts, never advice | yes, any stock |
| `desempenho` | "Was it worth it?" in a few numbers, computed server-side: return, max drawdown, volatility and a 21 x 100 moving-average crossover vs buy-and-hold, on the split-adjusted price and, when dividends are recorded, the TOTAL return (dividends and JCP reinvested on the ex-date). Open for every ticker | yes |
| `desempenho_fii` | The same for a real-estate fund (price only; distributions only in the total return; a daily jump above 35% is flagged `confiavel: false`) | yes |
| `desempenho_etf` | The same for an ETF (price only; a daily jump above 35% is flagged) | yes |
| `indice` | The benchmark: performance of a B3 index (IBOV, IFIX, SMLL...); empty code lists them | yes |
| `indice_precos` | Daily close of an index in points (30-session sample without a key) | sample |
| `bdr` | BDRs on B3: the list (open) or one BDR with returns, distributions in reais and splits | list yes; AAPL34 |
| `bdr_precos` | Daily prices of a BDR (30-session sample without a key) | sample |
| `precos` | The DAILY price series of one stock (open, high, low, close, volume), oldest first, plus the corporate events of the period; not adjusted. Without a key, a 30-session SAMPLE with a notice of how to get it all | WEGE3 yes; others sample, full needs a key |
| `eventos` | Splits, reverse splits, bonus issues and spin-offs with the source of each (B3-declared or found by us) and the net effect of the day | WEGE3 yes; others need a key |
| `dicionario` | Formula, CVM accounts and earnings base of each indicator, as JSON | yes |
| `metodologia` | The published methodology pages, as text | yes |
| `saude` | Current coverage and last ingestion | yes |

`trimestres` stops at Q3 on purpose. The interim filing (ITR) never carries a
standalone fourth quarter — it can be derived as `full year − nine months`, and
some do derive it. We do not: a figure we computed would sit in the same list as
the figures the company reported, carrying the error of two filings and erasing
the line between what was filed and what we calculated. For the closed year, ask
for the annual series.

**WEGE3** and the **whole methodology** are open, no key needed. For other
companies, create a **free key** at https://dadosb3.com/chave-gratis?de=github
(200 queries/day, no card) or subscribe to **Pro** at
https://dadosb3.com/assinar?de=github, and pass it in the `chave_api` argument or the
`DADOS_B3_API_KEY` environment variable.

The company count is deliberately not written here: the universe grows whenever
the CVM publishes, and a number frozen in a README ages without anyone
noticing. Call `saude` for today's figure.

## Banks and insurers

Financial institutions file under a different chart of accounts — there is no
EBIT and no sales revenue. The connector classifies them by their actual chart
of accounts and returns the indicators that mean something for them — **ROE,
margin, growth, P/E, P/B, dividends** — and deliberately does **not** publish
ROIC, EBITDA or EV/EBITDA for them, because those do not apply. Examples: Itaú,
Bradesco, Banco do Brasil, BB Seguridade, IRB.

## Why this one

A methodology published rather than described, invariant tests gating every
release, multiples with no future information leaking in, and **restatements
kept on the record** — when a company republishes a filing, both versions stay
side by side. An honest comparison, including where competitors are better:
**https://dadosb3.com/comparativo?de=github**

## Prefer plain Python?

`pip install dadosb3` — the official client for the same API, with typed
errors and one method per tool: <https://pypi.org/project/dadosb3/>

## Licence

MIT (this connector). The underlying data is public (CVM/B3); the service adds
standardisation, methodology and tests.

---

# Dados B3 — servidor MCP (bolsa brasileira, fundamentos auditáveis)

Conector [MCP](https://modelcontextprotocol.io) que dá ao seu agente de IA
(Claude, ChatGPT, Cursor e outros) acesso a **dados fundamentalistas das
companhias abertas brasileiras (B3) — inclusive bancos e seguradoras —, de 2010
até hoje**, com **metodologia 100% pública**: ROE, ROIC, margens, crescimento,
dívida líquida/EBITDA, **múltiplos ponto-no-tempo** (P/L, P/VP, EV/EBITDA com o
preço do 1º pregão *a partir da publicação real do balanço* — sem look-ahead,
próprio para backtest), **dividendos e dividend yield**, **scores prontos
(Piotroski F-Score e Graham)** e **histórico de reapresentações de balanço**.

Fonte: CVM (dados abertos, ODbL) e B3 (COTAHIST). Cada número carrega a conta
CVM de origem; **nada é publicado sem uma bateria de testes de invariantes
passando** (o balanço fecha, a DRE fecha, o preço nunca antecede a publicação).

Produto e planos: **https://dadosb3.com/?de=github**

## Uso 1 — remoto (nada para instalar, recomendado)

Adicione este conector remoto ao seu cliente de IA:

```
https://dadosb3.com/mcp/
```

No Claude: Configurações → Conectores → adicionar conector personalizado → cole a URL.

## Uso 2 — local (stdio)

```bash
pip install -r requirements.txt
python server.py
```

## Uso 3 — imagem Docker (um comando, sem Python local)

```bash
docker run -i --rm -e DADOS_B3_API_KEY=sua_chave_opcional ghcr.io/val7h/dados-b3-mcp:latest
```

A imagem é publicada a cada push na `main`. Ela existe por dois motivos: dar um
caminho de instalação de um comando só, e permitir que diretório