# @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](https://pipeworx.io) — 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):

```bash
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.):

```json
{
  "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:

```json
{
  "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

```bash
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.

```json
{
  "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](https://pipeworx.io/docs)
- [pipeworx.io](https://pipeworx.io)

## License

MIT