{
  "markdown": "# Dados B3 — MCP server (Brazilian stock market, auditable fundamentals)\n\n*[Português abaixo](#dados-b3--servidor-mcp-bolsa-brasileira-fundamentos-auditáveis)*\n\nAn [MCP](https://modelcontextprotocol.io) connector that gives your AI agent\n(Claude, ChatGPT, Cursor and others) access to **fundamentals for Brazilian\nlisted companies (B3) — banks and insurers included — from 2010 to today**,\nwith a **fully published methodology**: ROE, ROIC, margins, growth, net\ndebt/EBITDA, **point-in-time multiples** (P/E, P/B, EV/EBITDA priced at the\nfirst trading session *on or after* the day the filing actually became\npublic — no look-ahead, usable for backtests), **dividends and dividend yield**,\n**ready-made scores (Piotroski F-Score and Graham)** and a **record of restated\nfilings**.\n\nSources: CVM open data (ODbL) and B3 (COTAHIST). Every figure carries the CVM\naccount it came from, and **nothing is published unless a suite of invariant\ntests passes** — the balance sheet balances, the income statement reconciles,\nand a price never precedes the filing that justifies it.\n\nProduct and plans: **https://dadosb3.com**\n\n## Use 1 — remote (nothing to install, recommended)\n\nAdd this remote connector to your AI client:\n\n```\nhttps://dadosb3.com/mcp/\n```\n\nIn Claude: Settings → Connectors → add custom connector → paste the URL.\n\n## Use 2 — local (stdio)\n\n```bash\npip install -r requirements.txt\npython server.py\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"dados-b3\": {\n      \"command\": \"python\",\n      \"args\": [\"server.py\"],\n      \"env\": { \"DADOS_B3_API_KEY\": \"your_optional_key\" }\n    }\n  }\n}\n```\n\n## Use 3 — Docker image (one command, no local Python)\n\n```bash\ndocker run -i --rm -e DADOS_B3_API_KEY=your_optional_key ghcr.io/val7h/dados-b3-mcp:latest\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"dados-b3\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"-i\", \"--rm\", \"ghcr.io/val7h/dados-b3-mcp:latest\"]\n    }\n  }\n}\n```\n\nThe image is published on every push to `main`\n(`.github/workflows/publicar-imagem.yml`). It exists for two reasons: a\none-command install path, and letting MCP directories actually run the server\nin order to evaluate it.\n\n## Tools\n\n| Tool | What it does | Free? |\n|---|---|---|\n| `listar_empresas` | Every covered company (name, tax ID, ticker), banks and insurers included | yes |\n| `indicadores_anuais` | ROE, ROIC, margins, growth, net debt/EBITDA — annual series from 2010 | WEGE3 yes; others need a key |\n| `multiplos` | P/E, P/B, EV/EBITDA point-in-time; trailing P/E | WEGE3 yes; others need a key |\n| `fatos_contabeis` | Standardised accounts carrying the CVM code each figure came from | WEGE3 yes; others need a key |\n| `dividendos` | Cash distributions, annual summary and 12-month dividend yield | WEGE3 yes; others need a key |\n| `scores` | Piotroski F-Score with all nine criteria shown, plus the Graham test | WEGE3 yes; others need a key |\n| `reapresentacoes` | Restated filings — the original and the revised figure side by side | WEGE3 yes; others need a key |\n| `trimestres` | Quarterly series: Q1/Q2/Q3 accounts as filed, the quarter's price, margins and trailing ROE | WEGE3 yes; others need a key |\n| `hoje` | What changed in the last 30 days: filings published, filings **re-sent**, dividends, fund distributions, corporate actions, ticker changes | yes |\n| `fii` | One real-estate fund: point-in-time P/B, 12-month yield, vacancy, recent distributions | MXRF11 yes; others need a key |\n| `fiis` | Filters funds by P/B and dividend-yield ranges | key required |\n| `screener` | Filters the whole market by indicator ranges | key required |\n| `dicionario` | Formula, CVM accounts and earnings base of each indicator, as JSON | yes |\n| `metodologia` | The published methodology pages, as text | yes |\n| `saude` | Current coverage and last ingestion | yes |\n\n`trimestres` stops at Q3 on purpose. The interim filing (ITR) never carries a\nstandalone fourth quarter — it can be derived as `full year − nine months`, and\nsome do derive it. We do not: a figure we computed would sit in the same list as\nthe figures the company reported, carrying the error of two filings and erasing\nthe line between what was filed and what we calculated. For the closed year, ask\nfor the annual series.\n\n**WEGE3** and the **whole methodology** are open, no key needed. For other\ncompanies, create a **free key** (200 queries/day, no card) or subscribe to\n**Pro** at https://dadosb3.com, and pass it in the `chave_api` argument or the\n`DADOS_B3_API_KEY` environment variable.\n\nThe company count is deliberately not written here: the universe grows whenever\nthe CVM publishes, and a number frozen in a README ages without anyone\nnoticing. Call `saude` for today's figure.\n\n## Banks and insurers\n\nFinancial institutions file under a different chart of accounts — there is no\nEBIT and no sales revenue. The connector classifies them by their actual chart\nof accounts and returns the indicators that mean something for them — **ROE,\nmargin, growth, P/E, P/B, dividends** — and deliberately does **not** publish\nROIC, EBITDA or EV/EBITDA for them, because those do not apply. Examples: Itaú,\nBradesco, Banco do Brasil, BB Seguridade, IRB.\n\n## Why this one\n\nA methodology published rather than described, invariant tests gating every\nrelease, multiples with no future information leaking in, and **restatements\nkept on the record** — when a company republishes a filing, both versions stay\nside by side. An honest comparison, including where competitors are better:\n**https://dadosb3.com/comparativo**\n\n## Licence\n\nMIT (this connector). The underlying data is public (CVM/B3); the service adds\nstandardisation, methodology and tests.\n\n---\n\n# Dados B3 — servidor MCP (bolsa brasileira, fundamentos auditáveis)\n\nConector [MCP](https://modelcontextprotocol.io) que dá ao seu agente de IA\n(Claude, ChatGPT, Cursor e outros) acesso a **dados fundamentalistas das\ncompanhias abertas brasileiras (B3) — inclusive bancos e seguradoras —, de 2010\naté hoje**, com **metodologia 100% pública**: ROE, ROIC, margens, crescimento,\ndívida líquida/EBITDA, **múltiplos ponto-no-tempo** (P/L, P/VP, EV/EBITDA com o\npreço do 1º pregão *a partir da publicação real do balanço* — sem look-ahead,\npróprio para backtest), **dividendos e dividend yield**, **scores prontos\n(Piotroski F-Score e Graham)** e **histórico de reapresentações de balanço**.\n\nFonte: CVM (dados abertos, ODbL) e B3 (COTAHIST). Cada número carrega a conta\nCVM de origem; **nada é publicado sem uma bateria de testes de invariantes\npassando** (o balanço fecha, a DRE fecha, o preço nunca antecede a publicação).\n\nProduto e planos: **https://dadosb3.com**\n\n## Uso 1 — remoto (nada para instalar, recomendado)\n\nAdicione este conector remoto ao seu cliente de IA:\n\n```\nhttps://dadosb3.com/mcp/\n```\n\nNo Claude: Configurações → Conectores → adicionar conector personalizado → cole a URL.\n\n## Uso 2 — local (stdio)\n\n```bash\npip install -r requirements.txt\npython server.py\n```\n\n## Uso 3 — imagem Docker (um comando, sem Python local)\n\n```bash\ndocker run -i --rm -e DADOS_B3_API_KEY=sua_chave_opcional ghcr.io/val7h/dados-b3-mcp:latest\n```\n\nA imagem é publicada a cada push na `main`. Ela existe por dois motivos: dar um\ncaminho de instalação de um comando só, e permitir que diretórios de MCP rodem\no servidor para avaliá-lo.\n\n## Ferramentas\n\n| Ferramenta | O que faz | Grátis? |\n|---|---|---|\n| `listar_empresas` | Todas as companhias cobertas (nome, CNPJ, ticker), incl. bancos e seguradoras | sim |\n| `indicadores_anuais` | ROE, ROIC, margens, crescimento, DL/EBITDA — série anual desde 2010 | WEGE3 sim; demais com chave |\n| `multiplos` | P/L, P/VP, EV/EBITDA ponto-no-tempo; P/L TTM | WEGE3 sim; demais com chave |\n| `fatos_contabeis` | Contas padronizadas com a conta CVM de origem de cada número | WEGE3 sim; demais com chave |\n| `dividendos` | Proventos, resumo anual e dividend yield de 12 meses | WEGE3 sim; demais com chave |\n| `scores` | Piotroski F-Score com os nove critérios abertos, e o critério de Graham | WEGE3 sim; demais com chave |\n| `reapresentacoes` | Balanços republicados — versão original e revisada lado a lado | WEGE3 sim; demais com chave |\n| `trimestres` | Série trimestral: contas do 1T/2T/3T como publicadas, preço do trimestre, margens e ROE TTM | WEGE3 sim; demais com chave |\n| `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 |\n| `fii` | Um fundo imobiliário: P/VP ponto-no-tempo, DY de 12 meses, vacância, rendimentos recentes | MXRF11 sim; demais com chave |\n| `fiis` | Filtra fundos por faixas de P/VP e dividend yield | exige chave |\n| `screener` | Filtra o mercado inteiro por faixas de indicadores | exige chave |\n| `dicionario` | Fórmula, contas CVM e base do lucro de cada indicador, em JSON | sim |\n| `metodologia` | As páginas de metodologia publicadas, em texto | sim |\n| `saude` | Cobertura atual e última ingestão | sim |\n\n`trimestres` para no 3T de propósito. A ITR nunca traz o 4º trimestre isolado —\nele sai de `exercício cheio − 9 meses`, e há quem derive. Nós não: um número\ncalculado por nós entraria na MESMA lista dos que a companhia reportou,\ncarregando o erro de dois arquivos e apagando a fronteira entre \"foi publicado\"\ne \"nós calculamos\". Para o ano fechado, peça a série anual.\n\nA empresa **WEGE3** e a **metodologia** são abertas para degustação, sem chave.\nPara as demais, crie uma **chave grátis** (200 consultas/dia, sem cartão) ou\nassine o **Pro** em https://dadosb3.com e passe a chave no argumento\n`chave_api` (ou na variável `DADOS_B3_API_KEY`).\n\nA contagem de empresas não fica escrita aqui de propósito: o universo cresce\nquando a CVM publica, e um número congelado num README envelheceria sem\nninguém ver. Para o número de hoje, chame `saude`.\n\n## Bancos e seguradoras\n\nInstituições financeiras têm plano de contas próprio (não há EBIT nem receita\nde venda). O conector as classifica pelo plano de contas real e entrega os\nindicadores que fazem sentido — **ROE, margem, crescimento, P/L, P/VP,\ndividendos** — e **não** publica ROIC/EBITDA/EV-EBITDA para elas (não se\naplicam). Ex.: Itaú, Bradesco, Banco do Brasil, BB Seguridade, IRB.\n\n## Por que este e não outro\n\nMetodologia 100% pública, testes de invariantes antes de cada publicação,\nmúltiplos sem vazamento de informação futura, e **histórico de reapresentações\nregistrado**. Comparativo honesto, inclusive onde os concorrentes são\nmelhores: **https://dadosb3.com/comparativo**\n\n## Licença\n\nMIT (este conector). Os dados são públicos (CVM/B3); o serviço adiciona\npadronização, metodologia e testes.\n",
  "bytes": 10590,
  "sha": "b42de365b7f4b004f8666ae44c83d418dc62a853807521cc5f3668e41ed4865b",
  "repo_slug": "val7h/dados-b3-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_val7h_dados_b3_5c3a218e/readme"
}