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

Português abaixo

An MCP 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)

pip install -r requirements.txt
python server.py

{
  "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)

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

{
  "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
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 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)

pip install -r requirements.txt
python server.py

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

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órios de MCP rodem o servidor para avaliá-lo.

Prefere Python puro?

pip install dadosb3 — o cliente oficial da mesma API, com erros tratados e um método por ferramenta: https://pypi.org/project/dadosb3/

Ferramentas

Ferramenta	O que faz	Grátis?
listar_empresas	Todas as companhias cobertas (nome, CNPJ, ticker), incl. bancos e seguradoras	sim
indicadores_anuais	ROE, ROIC, margens, crescimento, DL/EBITDA — série anual desde 2010	WEGE3 sim; demais com chave
multiplos	P/L, P/VP, EV/EBITDA ponto-no-tempo; P/L TTM	WEGE3 sim; demais com chave
fatos_contabeis	Contas padronizadas com a conta CVM de origem de cada número	WEGE3 sim; demais com chave
dividendos	Proventos, resumo anual e dividend yield de 12 meses	WEGE3 sim; demais com chave
scores	Piotroski F-Score com os nove critérios abertos, e o critério de Graham	WEGE3 sim; demais com chave
reapresentacoes	Balanços republicados — versão original e revisada lado a lado	WEGE3 sim; demais com chave
trimestres	Série trimestral: contas do 1T/2T/3T como publicadas, preço do trimestre, margens e ROE TTM	WEGE3 sim; demais com chave
etfs_ranking	ETFs da B3: mais negociados, maior patrimônio, maior ágio/deságio sobre a cota do dia, retorno 12m pela cota, menor taxa EFETIVA	sim
etf	Um ETF: cota diária (FNET), ágio/deságio, taxa efetiva mês a mês, carteira (CDA) e sobreposição com pares	BOVA11 sim; demais com chave
auditar_amostra	Sorteia casos com a SUA semente para refazer cada número contra o arquivo da CVM (fórmula, conta, onde procurar)	sim
fiis_ranking	FIIs mais descontados (P/VP ponto-no-tempo), maiores DY 12m e mediana por segmento	exige chave
hoje	O que mudou nos últimos 30 dias: balanços publicados, balanços reenviados, proventos, rendimentos de FII, eventos societários, trocas de ticker	sim
fii	Um fundo imobiliário: P/VP ponto-no-tempo, DY de 12 meses, vacância, rendimentos recentes	MXRF11 sim; demais com chave
fiis	Filtra fundos por faixas de P/VP e dividend yield	exige chave
screener	Filtra o mercado inteiro por faixas de indicadores; as_of responde o que estava PÚBLICO numa data (sem olhar o futuro); recibo=True congela a resposta num endereço permanente, citável	exige chave
recibo	Lê uma consulta congelada do screener: pergunta, data de corte, versão do dado, resultado e o sha256 dele	sim
veredito	Resumo descritivo de uma ação: seis números em três perguntas, cada um com faixa numérica e comparação (mediana do setor, história da própria empresa, mercado inteiro), mais a bandeira de confiança do dado — fato, nunca conselho	sim, qualquer ação
desempenho	"Valeu a pena?" em poucos números, calculado no servidor: retorno, queda máxima, volatilidade e cruzamento de médias 21 x 100 contra comprar e manter, no preço ajustado por eventos e, quando há proventos, o retorno TOTAL (dividendos e JCP reinvestidos no data-ex). Aberto para qualquer ticker	sim
desempenho_fii	O mesmo para um fundo imobiliário (só preço; rendimentos só no retorno total; salto diário acima de 35% vem marcado confiavel: false)	sim
desempenho_etf	O mesmo para um ETF (só preço; salto diário acima de 35% vem marcado)	sim
indice	O benchmark: desempenho de um índice da B3 (IBOV, IFIX, SMLL...); código vazio lista	sim
indice_precos	Fechamento diário de um índice em pontos (amostra de 30 pregões sem chave)	amostra
precos	A série DIÁRIA de preços de uma ação (abertura, máxima, mínima, fechamento, volume), do mais antigo ao mais recente, mais os eventos societários do período; não ajustada. Sem chave, uma AMOSTRA de 30 pregões com o aviso de como ter tudo	WEGE3 sim; demais amostra, completa com chave
eventos	Desdobramentos, grupamentos, bonificações e cisões com a fonte de cada um (declarado pela B3 ou achado por nós) e o efeito líquido do dia	WEGE3 sim; demais com chave
dicionario	Fórmula, contas CVM e base do lucro de cada indicador, em JSON	sim
metodologia	As páginas de metodologia publicadas, em texto	sim
saude	Cobertura atual e última ingestão	sim

trimestres para no 3T de propósito. A ITR nunca traz o 4º trimestre isolado — ele sai de exercício cheio − 9 meses, e há quem derive. Nós não: um número calculado por nós entraria na MESMA lista dos que a companhia reportou, carregando o erro de dois arquivos e apagando a fronteira entre "foi publicado" e "nós calculamos". Para o ano fechado, peça a série anual.

A empresa WEGE3 e a metodologia são abertas para degustação, sem chave. Para as demais, crie uma chave grátis em https://dadosb3.com/chave-gratis?de=github (200 consultas/dia, sem cartão) ou assine o Pro em https://dadosb3.com/assinar?de=github e passe a chave no argumento chave_api (ou na variável DADOS_B3_API_KEY).

A contagem de empresas não fica escrita aqui de propósito: o universo cresce quando a CVM publica, e um número congelado num README envelheceria sem ninguém ver. Para o número de hoje, chame saude.

Bancos e seguradoras

Instituições financeiras têm plano de contas próprio (não há EBIT nem receita de venda). O conector as classifica pelo plano de contas real e entrega os indicadores que fazem sentido — ROE, margem, crescimento, P/L, P/VP, dividendos — e não publica ROIC/EBITDA/EV-EBITDA para elas (não se aplicam). Ex.: Itaú, Bradesco, Banco do Brasil, BB Seguridade, IRB.

Por que este e não outro

Metodologia 100% pública, testes de invariantes antes de cada publicação, múltiplos sem vazamento de informação futura, e histórico de reapresentações registrado. Comparativo honesto, inclusive onde os concorrentes são melhores: https://dadosb3.com/comparativo?de=github

Licença

MIT (este conector). Os dados são públicos (CVM/B3); o serviço adiciona padronização, metodologia e testes.