Skip to main content
Glama
cvm-mcp
by msperlin

cvm-mcp

PyPI Python License MCP

An MCP server for the CVM open-data repository (dados.cvm.gov.br) — the Brazilian securities regulator and the source behind the R packages GetDFPData2 and GetFREData.

It gives Claude Code, OpenCode, Cursor, VS Code, Codex, Gemini CLI and any other MCP client one interface to:

  • annual and quarterly financial statements (DFP / ITR)

  • the Formulário de Referência (FRE, 36 corporate tables)

  • fund NAVs, flows, portfolios and credit-fund reports

  • insider trading, governance, public offerings and sanctioning proceedings

  • ad-hoc SQL over everything, via DuckDB

15 datasets, 111 tables, 34 tools. Everything runs locally and read-only; data is downloaded on demand and cached on disk.

This server consolidates the earlier cvm-dfp-mcp and cvm-fre-mcp servers and is a strict superset of both.

Contents

Related MCP server: CVM (Valores Mobiliários)

Requirements

  • Python 3.10+ — uv installs and manages it for you.

  • uv — the only prerequisite.

  • Network access to dados.cvm.gov.br.

  • Disk space for the cache. It is lazy: nothing is downloaded until you ask for it. A full DFP + FRE history is a few GB; fi_cda is the heavy one (~270 MB uncompressed per month).

Install uv:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify with uv --version.

Quick start

The package is on PyPI.

Run without installing (best for trying it out and for client configs):

uvx cvm-mcp

This starts a stdio MCP server and waits for a client. Seeing no output is expected; press Ctrl+C to stop it.

Install a persistent cvm-mcp command (optional):

uv tool install cvm-mcp
cvm-mcp

If cvm-mcp is not found after installing, run uv tool update-shell and restart your terminal.

From source (for development):

git clone https://github.com/msperlin/cvm-mcp.git
cd cvm-mcp
uv sync
uv run cvm-mcp

Client setup

All configurations below run the server over stdio. They use uvx, which resolves and caches the package on first use.

GUI clients and PATH: Claude Desktop, Cursor and VS Code often do not inherit your shell PATH. If the server fails to start with “command not found”, run which uvx (macOS/Linux) or where uvx (Windows) and use that absolute path as command — commonly ~/.local/bin/uvx. Alternatively, uv tool install and use the absolute path to cvm-mcp.

Claude Code

Add it from the CLI, scoped to your user (available in every project):

claude mcp add --transport stdio --scope user cvm-mcp -- \
  uvx cvm-mcp

Check the connection:

claude mcp list

Or commit a project-scoped .mcp.json to the repository root:

{
  "mcpServers": {
    "cvm-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "cvm-mcp"
      ],
      "timeout": 600000
    }
  }
}

timeout is in milliseconds and applies per tool call. The first CVM download can take a while; 10 minutes is a safe ceiling.

OpenCode

OpenCode V2 configures servers under mcp.servers. Add it globally with the CLI:

opencode mcp add cvm-mcp --global -- \
  uvx cvm-mcp

Check it with opencode mcp list (or /mcps inside OpenCode).

Or edit ~/.config/opencode/opencode.json (global) or opencode.json (project):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "cvm-mcp": {
        "type": "local",
        "command": [
          "uvx",
          "cvm-mcp"
        ]
      }
    }
  }
}

The repository also ships a ready-to-copy opencode.example.json.

OpenCode V1 used server names directly under mcp; V2 uses mcp.servers.

Claude Desktop

Edit the Claude Desktop config file:

OS

Path

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "cvm-mcp": {
      "command": "uvx",
      "args": [
        "cvm-mcp"
      ]
    }
  }
}

Quit Claude Desktop completely and reopen it. The server appears under Connectors / the tools menu.

Cursor

Create ~/.cursor/mcp.json for all projects, or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "cvm-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "cvm-mcp"
      ]
    }
  }
}

Reload the window if the server does not appear under Customize → MCP.

VS Code / GitHub Copilot

Create .vscode/mcp.json in the workspace:

{
  "servers": {
    "cvm-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "cvm-mcp"
      ]
    }
  }
}

VS Code uses the servers key. Portable .mcp.json files (Claude Desktop, Cursor, Cline, etc.) use mcpServers instead — do not mix the two.

You can also run MCP: Add Server from the Command Palette and choose Command (stdio) with:

uvx cvm-mcp

Codex CLI

Add to ~/.codex/config.toml (or .codex/config.toml in a trusted project):

[mcp_servers.cvm-mcp]
command = "uvx"
args = ["cvm-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 600

Codex reads server instructions and exposes the tools automatically. Use /mcp in a Codex session to inspect the connection.

Gemini CLI

Add to ~/.gemini/settings.json (user) or .gemini/settings.json (project):

{
  "mcpServers": {
    "cvm-mcp": {
      "command": "uvx",
      "args": [
        "cvm-mcp"
      ],
      "timeout": 600000
    }
  }
}

Then run /mcp inside Gemini CLI to check the connection. timeout is in milliseconds.

Continue

Create .continue/mcpServers/cvm-mcp.yaml:

name: CVM MCP
version: 0.0.1
schema: v1
mcpServers:
  - name: CVM
    type: stdio
    command: uvx
    args:
      - "cvm-mcp"

Continue can also import the JSON block from the Other MCP clients section into .continue/mcpServers/.

Other MCP clients

Most clients accept a stdio server in this shape:

{
  "mcpServers": {
    "cvm-mcp": {
      "command": "uvx",
      "args": [
        "cvm-mcp"
      ]
    }
  }
}

If your client asks for a single command line:

uvx cvm-mcp

Windows clients that cannot find uvx can use the executable installed by uv tool install directly, e.g. C:\Users\<you>\.local\bin\cvm-mcp.exe.

Example prompts

Once connected, ask in natural language:

  • “What were Vale's revenue, EBIT and net debt in 2024? Cite the CVM/DFP accounts.”

  • “Compare the last five years of ROE, net margin and net debt/EBITDA for Petrobras, Vale and Itaú.”

  • “Show the board composition, compensation and shareholders of Banco do Brasil in the latest Formulário de Referência.”

  • “Which insiders bought or sold WEG shares in the last six months?”

  • “List the largest FIDCs by net asset value in the latest month, with delinquency and credit segments.”

  • “How much did Brazilian companies raise in public offerings in 2024, by asset type and lead underwriter?”

  • “Find sanctioning proceedings mentioning insider trading since 2023.”

  • “Load DFP 2024 and run a SQL query joining the income statement with the company registry.”

  • “What does Vale's explanatory note on provisions say for 2024? Quote the relevant passage and the PDF page.”

The server is instructed to cite the dataset and reference period and never to invent figures.

Datasets

Domain

Datasets

Coverage

Companies

dfp, itr (statements + filing index + pareceres + share composition), fre (36 tables), fca, vlmo (insider trading), cgvn (governance)

DFP/ITR/FRE 2010+; FCA/VLMO/CGVN 2018+

Funds

fi_inf_diario, fi_cda, fi_cad, fii_inf_mensal, fidc_inf_mensal (18 tables), fiagro_inf_mensal

FI daily 2021-01+; CDA 2023-01+; FII 2016+; FIDC 2025-01+; FIAGRO 2025-05+

CVM renaming the fund columns is handled at load time. RCVM 175 did it in the Dec/2023 archives (CNPJ_FUNDO → CNPJ_FUNDO_CLASSE, TP_FUNDO → TP_FUNDO_CLASSE, new ID_SUBCLASSE), affecting the FI daily report, the CDA blocks and the CDA net-asset-value table; the FII monthly report had already changed in Jan/2021 (CNPJ_Fundo/Nome_Fundo → ..._Classe). The CDA structured portfolio moved from cda_fiim_* to cda_fie_* in Feb/2024, and gained the optional CONFID members in 2026. Old headers are mapped onto the current schema, so a query spanning 2023-11 and 2023-12 sees one layout. | Offerings | oferta (ICVM 400 / RCVM 160) | 1988+ | | Enforcement | sancionador (PAS) | current | | Registry | cad_cia_aberta | current |

Use list_datasets from a client to see the exact table names and view names. describe_dataset shows columns and coverage; describe_dataset(detail=True) adds units and caveats.

Tools

There are two layers.

Curated tools for the common questions:

Group

Tools

Identity

search_company, resolve, list_companies, get_tickers

Statements

list_account_codes, get_financial_statements, get_account_history, get_statement_summary

Corporate filings

list_fre_tables, get_fre_table, get_company_overview, get_shareholders, get_compensation, get_board, get_capital

Filings & notes

get_dfp_document, get_dfp_notes, search_dfp_notes

Insiders & governance

get_insider_trades, insider_summary, governance_practices, governance_score

Funds

search_fund, get_fund_nav, get_fund_flows, get_fund_portfolio, get_fidc_report, rank_funds

Offerings

search_offerings, issuance_volume, league_table

Meta tools support both layers:

Tool

Purpose

list_datasets

All datasets, tables and DuckDB view names

describe_dataset

Columns, cached periods and (with detail=True) column meanings

load_dataset

Download/parse a dataset or period without forcing a refresh

cache_status

What is cached, per dataset, with sizes

refresh_cache

Force a re-download and rebuild

run_query

Read-only DuckDB SQL over every cached table

run_query sees tables as <dataset>__<table>, e.g. dfp__dre_con, fi_inf_diario__informe, vlmo__transacoes. Only cached periods exist, so call load_dataset first when you need a specific period.

Configuration

All settings are optional environment variables:

Variable

Default

Meaning

CVMMCP_CACHE_DIR

~/.cache/cvm-mcp

Cache root (downloads + Parquet)

CVMMCP_REFRESH_HOURS

12

Revalidation window for CVM archives; 0 disables revalidation

MCP_TRANSPORT

stdio

stdio, streamable-http or sse

MCP_HOST

127.0.0.1

Host for the HTTP transports

MCP_PORT

8000

Port for the HTTP transports

Add CVMMCP_CACHE_DIR wherever your client expects environment variables:

{
  "env": {
    "CVMMCP_CACHE_DIR": "/absolute/path/to/cvm-cache"
  }
}

For a long-running HTTP server:

MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 cvm-mcp

The HTTP transports have no authentication; bind to localhost or put the server behind a reverse proxy.

Cache

~/.cache/cvm-mcp/
├── downloads/                     raw zips and CSVs, revalidated with If-Modified-Since
│   └── <archive>.meta.json        remote Last-Modified/ETag + last revalidation time
└── parquet/v1/<dataset>/<table>/period=<YYYY|YYYYMM|all>/data.parquet
    └── doc_text/{pagina,nota}/<dfp|itr>/<year>-<cd_cvm>/data.parquet
  • Everything is lazy. The first call for a dataset downloads and parses the CVM archive; later calls read the Parquet partition.

  • CVM rewrites the current month in place, so archives are revalidated every 12 h by default (CVMMCP_REFRESH_HOURS).

  • A 304 Not Modified updates only the sidecar's checked_at; the archive mtime stays put, so the Parquet partition is reused instead of being parsed again.

  • load_dataset populates the cache without forcing a refresh. refresh_cache forces a re-download and rebuild.

  • cache_status reports datasets, periods, partition counts and bytes. To reclaim space, delete ~/.cache/cvm-mcp/parquet (it is rebuilt on demand) or point CVMMCP_CACHE_DIR at a larger disk.

Data notes

  • DFP / ITR keep CVM's uppercase column names. VL_CONTA is the raw value; VL_CONTA_BRL is already scaled by ESCALA_MOEDA and is the number to report.

  • Notas explicativas are not a CVM table. They are free text inside the full filing, whose download link is link_doc in dfp__documento / itr__documento. get_dfp_notes downloads that ZIP, extracts the PDF text and indexes the numbered notes; search_dfp_notes searches every page. Treat the note boundaries as best effort and cite the PDF page it returns.

  • DFP/ITR extras: documento (filing index with link_doc), parecer (free text, off by default because it is ~15 MB per year) and composicao_capital. dra (statement of comprehensive income) is available as dfp__dra_con/ind and itr__dra_con/ind.

  • FRE keeps the GetFREData-compatible snake_case schema and key block (cd_cvm, cnpj, nome_companhia, data_referencia, versao, id_documento).

  • Newer datasets (VLMO, CGVN, funds, offerings) are normalized to snake_case and gain a 14-digit cnpj column and a _period column.

  • fi_cda is heavy (~270 MB uncompressed per month). Build one block/period at a time; load_dataset refuses more than three periods of a heavy dataset in one call.

Fund family routing

CVM splits funds by instrument, not by manager, and the tools hide that. get_fund_nav and get_fund_portfolio resolve the class CNPJ in fi_cad, read its tipo_classe and pick the dataset:

Family

Series

Portfolio

FIF / FAPI

fi_inf_diario (daily)

fi_cda blocks 1–8

FII

fii_inf_mensal (monthly)

fii_inf_mensal/ativo_passivo

FIDC

fidc_inf_mensal/tab_iv

fidc_inf_mensal/tab_ii (credit segments)

FIAGRO

fiagro_inf_mensal

fi_cda/fie

get_fidc_report adds the credit dashboard (assets, portfolio, PL, delinquency).

Known gaps: FIP is quarterly and is not wired up yet; the tools say so explicitly. FIDC monthly reports start in 2025-01 — 2013–2024 lives in the HIST/ folder with a different layout and is not wired up. FII history starts in 2016.

How it works

The portal has ~1,259 files and ~10 GB of archives, but only about five shapes of data. Each dataset is described declaratively in registry.py — URL pattern, period granularity, tables inside the archive, normalizer — and the store turns every (dataset, table, period) into one Parquet partition. Adding a dataset is a data change, not a code change.

src/cvm_mcp/
├── app.py             MCP application object + server instructions
├── registry.py        declarative catalog of datasets and tables
├── fetch.py           download, revalidation, metadata sidecars, file locks
├── store.py           Parquet partitions + DuckDB views + read-only SQL
├── normalize.py       Latin-1 reader, header cleaning, CNPJ, type inference
├── identity.py        CNPJ ↔ cd_cvm ↔ ticker resolution
├── schema_dfp.py      canonical DFP/ITR schema
├── doc_text.py        filing PDF download, text extraction and note splitting
├── catalog_dfp.py     curated chart of accounts and roles
├── catalog_fre.py     the 36 FRE tables
├── fre_normalize.py   FRE normalization
├── data_dictionary.py curated column descriptions, units and caveats
├── tools_*.py         the MCP tools, one module per domain
└── server.py          entry point

Each archive is downloaded once and revalidated with If-Modified-Since; downloads are guarded by a cross-process file lock, and SQL is restricted to a single read-only SELECT / WITH over the cached views.

Development

git clone https://github.com/msperlin/cvm-mcp.git
cd cvm-mcp
uv sync

uv run pytest -m "not network"      # fast, offline
uv run pytest -m network            # hits dados.cvm.gov.br
uv run python scripts/smoke_mcp.py  # end-to-end stdio smoke test

To run the working tree instead of the GitHub package in a client config, point the command at the checkout:

{
  "command": "uv",
  "args": ["run", "--directory", "/absolute/path/to/cvm-mcp", "cvm-mcp"]
}

Releasing

Publishing happens on GitHub, not from a laptop, through PyPI trusted publishing (OIDC), so no API token is stored anywhere.

  1. Bump version in pyproject.toml and commit it.

  2. Tag the commit with a matching v prefix and push it:

    git tag v0.1.0
    git push origin v0.1.0
  3. Draft a GitHub release for that tag and publish it.

The publish workflow in .github/workflows/publish.yml then runs the offline test suite, builds the sdist and wheel, checks the metadata, verifies the tag matches the version, and uploads to PyPI. Re-running it manually (workflow_dispatch) rebuilds and re-uploads the current version, which PyPI rejects if the files already exist — so only do that after a failed release.

One-time setup (already required before the first upload): on PyPI, add a pending publisher for project cvm-mcp with owner msperlin, repository cvm-mcp, workflow publish.yml, and environment pypi. The matching environment is declared in the workflow.

Troubleshooting

Symptom

Fix

uvx: command not found

Install uv, or use the absolute path from which uvx / where uvx. GUI clients often do not inherit PATH.

Server starts but no tools appear

Check the client's MCP panel: claude mcp list, opencode mcp list, /mcp in Gemini/Codex/Cursor/VS Code. Restart the app after editing JSON.

First tool call is slow

The server is downloading and parsing a CVM archive. Use load_dataset for the exact period you need, and raise the client's tool timeout. fi_cda is the heaviest dataset.

run_query says “no data cached”

Only cached periods are visible to SQL. Call load_dataset (e.g. dataset="dfp", period="2024") or a curated tool first.

The latest month looks stale

CVM rewrites the current month in place. Call refresh_cache for that dataset/period.

Disk is filling up

Check cache_status; delete ~/.cache/cvm-mcp/parquet (rebuilt on demand) or move CVMMCP_CACHE_DIR.

CVM returned HTTP 5xx / timeouts

CVM is temporarily unavailable; the server retries 429/500/502/503/504 with backoff. Check connectivity to dados.cvm.gov.br.

Unknown dataset/table

Call list_datasets and describe_dataset; ids and table slugs are exact.

License

MIT. CVM data is public; see the CVM open-data portal for the original terms and update policy.

Available Tools

37 tools
cache_statusB
Read-only

What is already downloaded and parsed locally, per dataset.

Inputs: no named parameters. Returns: result

describe_datasetA
Read-only

Show the tables, cached periods and columns of one dataset.

Columns come from the local cache; if a table was never queried, columns is empty — call the corresponding data tool once to populate it. With detail=True, column_details explains units and pitfalls (e.g. VL_CONTA vs VL_CONTA_BRL, or FRE percentages).

Inputs: dataset (required), table, detail. Returns: result

get_account_historyB
Read-only

Follow one account over time for one or more companies (a compact series).

Inputs: account (required), cvm_codes (required), by, format, +5 more. Returns: result

get_boardC
Read-only

Board, officers and fiscal council composition.

Inputs: year (required), cd_cvm (required), version. Returns: result

get_capitalB
Read-only

Share capital events: amounts, approvals and share counts.

Inputs: year (required), cd_cvm (required), version. Returns: result

get_company_overviewA
Read-only

Show which FRE tables have data for one company-year.

Downloads and parses the whole year once (the first call can take a while).

Inputs: year (required), cd_cvm (required). Returns: result

get_compensationC
Read-only

Compensation of the board, officers and fiscal council.

Inputs: year (required), cd_cvm (required), detail, version. Returns: result

get_dfp_documentA
Read-only

Filing metadata and the download link of the full document.

The link points to the CVM ZIP with the complete filing: an XML with the statement numbers, a PDF with the notas explicativas and the company data. Use get_dfp_notes to read the notes without handling the file yourself.

Inputs: year (required), cvm_codes (required), data_type. Returns: result

get_dfp_notesA
Read-only

Read the explanatory notes of one company/year.

Without note and pages, lists the detected numbered notes (number, title, pages). The first call for a company/year downloads the filing PDF (~15 MB) and extracts its text; later calls read the local cache.

Inputs: year (required), cvm_code (required), note, pages, +2 more. Returns: result

get_fidc_reportA
Read-only

Credit-fund dashboard: assets, portfolio, net asset value and delinquency.

inadimplencia_pct is the overdue credit over the total credit portfolio (tables I.2A.2 and I.2 of the FIDC monthly report).

Inputs: fund (required), last_period, first_period. Returns: result

get_financial_statementsB
Read-only

Full statement lines for one or more companies, as CSV.

One row per reported account, with the raw value (VL_CONTA) and the value in reais (VL_CONTA_BRL).

Inputs: cvm_codes (required), format, doc_type, max_rows, +3 more. Returns: result

get_fre_tableB
Read-only

Read rows from one FRE table, filtered by company and year.

The generic workhorse; prefer the curated helpers when they fit.

Inputs: table (required), cd_cvm, columns, version, +3 more. Returns: result

get_fund_flowsA
Read-only

Monthly subscriptions, redemptions and net flow for one FI fund.

Only FIF/FAPI report daily subscriptions and redemptions (Informe Diário). FII, FIDC and FIAGRO do not publish a flow series in the monthly report.

Inputs: fund (required), last_period, first_period. Returns: result

get_fund_navA
Read-only

NAV time series for any fund, routed to the right CVM dataset.

  • FIF/FAPI: daily quota, net asset value, subscriptions, redemptions, unitholders.

  • FII: monthly net asset value, book value per share, unitholders, dividend yield.

  • FIDC: monthly net asset value and average NAV.

  • FIAGRO: monthly net asset value, unitholders, returns and fees.

Inputs: fund (required), max_rows, last_period, first_period. Returns: result

get_fund_portfolioA
Read-only

Holdings of any fund, routed to the right dataset.

  • FIF/FIAGRO: CDA portfolio (asset, issuer, quantity, market value, cost).

  • FII: balance-sheet composition (properties, CRI, FII quotas, cash...).

  • FIDC: credit portfolio by segment (industrial, real estate, payroll...).

The output is long-form: one row per component, with its value in BRL.

Inputs: fund (required), block, period, max_rows. Returns: result

get_insider_tradesB
Read-only

Transactions by controllers, officers and board members (CVM/VLMO).

Returns who traded, the role, the movement type, date, quantity, unit price and volume. This is the insider-trading signal dataset (Instruction 358).

Inputs: company (required), role, max_rows, last_year, +2 more. Returns: result

get_shareholdersC
Read-only

Shareholder position: who owns the company and how much.

Inputs: year (required), cd_cvm (required), version, max_rows. Returns: result

get_statement_summaryB
Read-only

Compact headline view of one company-year: totals, equity, revenue, profit.

Returns the top-level accounts with a role column (total_assets, equity, revenue, ebit, net_income, ...).

Inputs: cvm_code (required), year, depth, format, +2 more. Returns: result

get_tickersC
Read-only

Map tickers (PETR4, VALE3) to CVM codes and company names.

Inputs: year, limit, ticker, cvm_codes. Returns: result

governance_practicesB
Read-only

Explain-or-comply governance report: each practice and whether it was adopted.

Inputs: year (required), company (required), adopted, chapter, +1 more. Returns: result

governance_scoreC
Read-only

Adoption rate of the recommended governance practices, overall and by chapter.

Inputs: year (required), company (required). Returns: result

insider_summaryB
Read-only

Net insider buying/selling by year and role (aggregate of VLMO).

Inputs: company (required), last_year, first_year. Returns: result

issuance_volumeA
Read-only

Total offering volume, grouped by year, asset type, issuer, lead or rite.

valor_total is as reported by CVM; amounts from different decades are not inflation-adjusted.

Inputs: rite, limit, group_by, last_date, +2 more. Returns: result

league_tableB
Read-only

Rank lead underwriters by total offering volume (the ECM/DCM league table).

Inputs: rite, limit, last_date, asset_type, +1 more. Returns: result

list_account_codesA
Read-only

List the curated account codes and role names understood by this server.

Inputs: doc_type. Returns: result

list_companiesB
Read-only

Browse the CVM company registry, optionally filtered by sector.

Inputs: limit, offset, sector, status. Returns: result

list_datasetsA
Read-only

List every CVM dataset this server understands.

This is the entry point: each dataset has an id, a period granularity and one or more tables. Table ids are what describe_dataset and run_query use; SQL views are named <dataset>__<table>.

Inputs: detail, domain. Returns: result

list_fre_tablesB
Read-only

List the 36 FRE corporate tables understood by this server.

Inputs: detail. Returns: result

load_datasetA
Read-only

Download and parse a dataset/period into the local cache.

This is the non-destructive counterpart of refresh_cache: it reuses archives that are still fresh and only builds the partitions that are missing. Call it before run_query so the SQL layer has the tables (and periods) it needs, and use describe_dataset(detail=True) for column meanings.

Heavy optional tables (dfp/itr parecer) are skipped unless named in table or include_optional is true.

Inputs: dataset (required), table, period, include_optional. Returns: result

rank_fundsB
Read-only

Rank FI funds in one month by net asset value, net flow, return or unitholders.

Inputs: limit, metric, period, fund_type. Returns: result

refresh_cacheA
Read-only

Force a re-download and rebuild of cached partitions.

CVM rewrites the current period in place, so use this when the latest month looks stale.

Inputs: dataset (required), table, period. Returns: result

resolveB
Read-only

Resolve any identifier to the CVM keys (cd_cvm, CNPJ, ticker, name).

Inputs: query (required). Returns: result

run_queryA
Read-only

Run SQL across cached CVM tables (DuckDB engine).

Use it for questions that combine datasets, for aggregates the curated tools do not expose, and to inspect a table before writing a longer query. Only SELECT/WITH is allowed; the result is capped by limit.

Inputs: sql (required), limit. Returns: result

search_companyA
Read-only

Find the CVM code (cd_cvm) of a company by name, CNPJ, ticker or code.

Accent- and case-insensitive. This is the entry point for every corporate tool: they key on cd_cvm, never on the ticker.

Inputs: query (required), limit, status. Returns: result

search_dfp_notesA
Read-only

Search the extracted text of the filing, returning snippets with pages.

Searches every page (not only the detected notes) so a hit is never lost to a segmentation failure. Each match carries the PDF page and, when known, the number of the note it belongs to.

Inputs: term (required), year (required), cvm_codes (required), limit, +2 more. Returns: result

search_fundA
Read-only

Find a fund or class and get the CNPJ used by every fund tool.

The CVM keys fund data on the class CNPJ. The result carries a family (fi, fii, fidc, fiagro, fip) that tells which monthly report covers it — get_fund_nav routes automatically.

Inputs: query (required), limit. Returns: result

search_offeringsB
Read-only

Search registered, exempt and restricted public offerings since 1988.

Inputs: rite, limit, issuer, last_date, +2 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 37 tools

    Disambiguation3/5

    Most tools target a distinct resource (funds vs filings vs offerings), and descriptions explicitly flag overlaps (get_fre_table is 'the generic workhorse; prefer the curated helpers'). However, several pairs genuinely overlap: search_company/resolve/get_tickers/list_companies all answer 'which company is this?', and get_financial_statements/get_statement_summary/get_account_history/run_query all serve statement retrieval. An agent must read descriptions carefully to pick correctly.

    Naming Consistency4/5

    The dominant pattern is verb_noun (get_fund_nav, list_companies, search_offerings, rank_funds), applied consistently across the bulk of the 37 tools. A handful of noun-first outliers break the pattern: resolve, insider_summary, cache_status, governance_score, issuance_volume, league_table. Minor deviation, still readable.

    Tool Count2/5

    37 tools is well past the heavy threshold, and while the CVM domain is genuinely broad, some tools are convenience wrappers over others (resolve duplicates search_company/get_tickers; curated FRE helpers layer on get_fre_table; run_query can approximate several tools). The surface feels like an accumulation of sub-products rather than a tightly scoped set.

    Completeness4/5

    Coverage is broad for a read-only regulatory-data server: identity resolution, DFP/ITR statements and notes, FRE corporate tables, all fund families (FI/FII/FIDC/FIAGRO), insider trading, offerings/issuance, governance, plus cache and SQL escape hatches. Minor gaps remain (e.g. dedicated quarterly ITR view, dividends/events, fund performance history beyond NAV), but agents can work around them via run_query.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server that fetches Brazilian financial data from the CVM open data portal and exposes tools for LLM clients to query companies and calculate financial indicators from published financial statements.
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables querying the Brazilian Securities Commission (CVM) registry for individuals or companies using CPF or CNPJ. Provides a single read-only MCP tool, cvm_consultar.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides a single read-only MCP tool to query the official Brazilian SEC (CVM) database on registered participants, hosted with prepaid per-query pricing and no platform credentials.
      MIT