Brazil Cvm Financials MCP Server

@pipeworx/brazil-cvm-financials

Annual financial statements (balance sheet, income statement, cash flow, value added) of Brazilian listed companies, from CVM (Comissao de Valores Mobiliarios) open data -- by CNPJ or company name, with CVM account codes and labels, in full BRL.

Part of Pipeworx — an MCP gateway connecting AI agents to 1863+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.

Tools

• br_financials(cnpj | name, year?, scope?, statement?, max_depth?, limit?, offset?) -- the statements of one company for one fiscal year as account lines (code, Portuguese label, value in BRL). Default depth 2 returns the headline lines; raise max_depth for sub-accounts. States the scope (consolidated/individual), the filing version and the filed scale on every response. A company or year not in the data returns found:false with data_as_of.
• br_financials_search(name, limit?) -- find companies by name (every word must match, accents ignored); returns CNPJ, CVM code and the fiscal years available.
• br_financial_series(cnpj | name, account_code, from_year?, to_year?, scope?) -- one account across years (e.g. 3.01 income-statement top line, 1 total assets, 2.03 equity), with the label, scope and filing version of each year, and missing_years listed rather than dropped.

Auth

Keyless.

Data sources

• CVM (Comissao de Valores Mobiliarios, Brazil), open data -- annual financial statements (DFP) of listed companies, fiscal years 2019 onward.

Licence. CVM publishes this dataset under the Open Data Commons Open Database License (ODbL). The data here is a database copy, so ODbL applies to it: attribution to CVM and share-alike on the database. Every response carries the source and licence fields.

What is in the copy, and what is not -- read before quoting a number.

• Latest filing version only. CVM's archives carry every revision of a filing as extra rows (and are refreshed weekly with re-filings). Only the highest version per company + reference date is kept; the response reports filing_version and filing_versions_seen. Superseded revisions are not available.
• Current-year column only. Each filing also reports the prior year as a comparative; that column is dropped (it is restated data that appears as the current column of the next year's own filing). So a figure is "as filed for that fiscal year", not "as restated later".
• Statements kept: balance sheet assets (BPA) and liabilities/equity (BPP), income statement (DRE), cash flow indirect (DFC_MI) and direct (DFC_MD), value added (DVA), consolidated and individual. Not kept: statement of changes in equity, comprehensive income, auditor opinions, share-capital composition.
• Scope: consolidated is the group; individual is the parent company alone. The default is consolidated where the company filed one.
• Scale and currency: filers state values in units or thousands; the response applies the multiplier and returns full BRL, naming the filed scale. All loaded statements are in BRL.
• Charts differ by sector. CVM account codes follow one numbering (1 assets, 2 liabilities and equity, 3 income, 6 cash flow, 7 value added) but banks and insurers use a different income-statement chart: 3.01 is revenue for an industrial and financial-intermediation income for a bank. The label comes back with every value so a mismatch is visible.
• Per-share lines: earnings-per-share accounts (3.99.*) are BRL per share and are NOT multiplied by the filed scale; they come back as value_brl_per_share.
• Fiscal-year labels follow the reference date; a company with a non-December year-end is listed under the calendar year of its reference date.

Updating the data

CVM re-files weekly. Reload with (needs wrangler logged in to the Pipeworx Cloudflare account):

node scripts/brazil-cvm-financials/load-data.mjs --from 2019

The loader DROPs and reloads the tables, verifies the row counts against what it generated and exits non-zero if they differ. data_as_of in every response is the date of the last load; latest_filing_received is the newest filing receipt date in it.

Quick Start

Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "brazil-cvm-financials": {
      "url": "https://gateway.pipeworx.io/brazil-cvm-financials/mcp"
    }
  }
}

What this endpoint actually serves

tools/list at https://gateway.pipeworx.io/brazil-cvm-financials/mcp returns the tools in the table above plus the shared Pipeworx meta-tools — ask_pipeworx, discover_tools, search_within, remember/recall and the rest of the gateway-wide set. So the tool count you see is larger than this table: a single-pack endpoint currently lists roughly 30 shared tools alongside the pack's own. The connection's initialize response states its exact scope, and is the authoritative answer for a given day.

This is deliberate, not multiplexing by accident. The meta-tools are what let a scoped connection answer a question this pack does not cover — via ask_pipeworx, which routes across the whole catalog — without you adding a second MCP server. There is currently no way to mount a pack endpoint without them; if the extra schemas cost you more context than the routing is worth, connect to the full gateway once rather than to several pack endpoints.

Or connect to the full Pipeworx gateway to get every pack's tools listed directly, instead of just this one's:

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

Both URLs reach the same gateway and the same 1863+ data sources. The only difference is which pack's tools are listed directly; ask_pipeworx reaches all of them from either one.

No MCP client? Call it over HTTP

curl -X POST https://gateway.pipeworx.io/v1/tools/br_financials \
  -H 'Content-Type: application/json' \
  -d '{"cnpj":"33.000.167/0001-01","year":2024,"statement":"DRE"}'

No account needed for the first calls. Inspect any tool: GET https://gateway.pipeworx.io/v1/tools/br_financials. Find one: POST https://gateway.pipeworx.io/v1/tools/search_packs with {"query":"..."}.

Run it from npm

@pipeworx/mcp-brazil-cvm-financials is a local stdio bridge to the Pipeworx gateway: your MCP client starts it with npx, and it forwards every call to the same https://gateway.pipeworx.io/brazil-cvm-financials/mcp endpoint shown above. It needs network access; there is no offline mode.

{
  "mcpServers": {
    "brazil-cvm-financials": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-brazil-cvm-financials"]
    }
  }
}

Without a key it calls anonymously, capped at 50 calls a day. A free account raises that to 200 a day: get a key at https://pipeworx.io/signup and add "env": { "PIPEWORX_API_KEY": "<your key>" } to the server entry. The key is sent as a Bearer token, the same way a hosted connection sends it, so calls are metered and billed exactly as they are there.

It lists only this pack's tools by default. Set PIPEWORX_META_TOOLS=1 to also list ask_pipeworx and the other gateway-wide tools.

Behind an HTTPS proxy: Node's built-in fetch does not read HTTPS_PROXY by default. Newer Node releases honour it when NODE_USE_ENV_PROXY=1 is set; check your Node version's documentation.

Using with ask_pipeworx

Instead of calling tools directly, you can ask questions in plain English — this works on the pack endpoint above as well as on the full gateway:

ask_pipeworx({ question: "your question about Brazil Cvm Financials data" })

The gateway picks the right tool and fills the arguments automatically.

More

• Docs and guides
• pipeworx.io

License

MIT