cvm-mcp

MCP server that fetches and processes financial data directly from the CVM Open Data Portal (dados.cvm.gov.br), without relying on third parties. It exposes tools for an LLM client (Claude Desktop, Claude Code, etc.) to query the financial statements published by publicly traded companies.

The default view is quarterly: the tools start from the last quarter the company published and return the previous 12 months, quarter by quarter, with the accounting accounts as published by the CVM — without calculated indicators.

What it does

All monetary values are normalized to R$ millions. See Limitations below — the AI always receives warnings when a data point is derived or could not be obtained.

Related MCP server: FinancialReports MCP Server

How the quarter is assembled

The CVM's ITR publishes only Q1, Q2, and Q3, and already brings each quarter isolated in addition to the year-to-date accumulations — so cutting a quarter is filtering by period, not subtracting.

Q4 does not exist in the ITR. It is derived as exercício completo (DFP) − acumulado até o 3T (ITR), matched account by account by the accounting code. Every such period is marked with derivado: true in the response, along with an explicit warning.

Two consequences worth understanding:

• Stock accounts are never derived. BPA and BPP are balances on a date, so the year-end closing is already the Q4 value. Only flow accounts (DRE, DFC, DVA, DRA, DMPL) undergo subtraction.

• The "last quarter" is per company, not global. Non-calendar fiscal years close in other months — Camil, for example, has quarters Mar–May, Jun–Aug, Sep–Nov, and Dec–Feb. The server resolves this by each company's dates, and the label (2T26) is always accompanied by inicio and fim.

Installation

Requires Python 3.10+. Works the same on Windows, macOS, and Linux.

Option 1 — pipx (recommended, isolates the environment)

pipx install .

Runs from any folder afterwards, as the command cvm-mcp.

Option 2 — pip in a virtual environment

python -m venv .venv
# Windows (PowerShell)
.venv\Scripts\Activate.ps1
# macOS / Linux
source .venv/bin/activate

pip install -e .

Option 3 — directly from source, without installing

pip install -r requirements.txt   # ou: pip install mcp[cli] httpx pandas platformdirs
python -m cvm_mcp

Configuring in Claude Desktop

Edit claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json; macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) and add:

{
  "mcpServers": {
    "cvm": {
      "command": "cvm-mcp"
    }
  }
}

If you prefer not to install with pipx (Option 3), use:

{
  "mcpServers": {
    "cvm": {
      "command": "python",
      "args": ["-m", "cvm_mcp"]
    }
  }
}

Local cache

The files downloaded from the CVM (registry + annual ZIPs of ITR and DFP) are cached locally to avoid re-downloading on every query — the check uses ETag/Last-Modified, so updates on the CVM portal are detected automatically.

Worth sizing: the packages come compressed (~20–30 MB per year), but are extracted for use, and each year-type takes up a few hundred MB on disk. The quarterly view typically touches two years of ITR plus one year of DFP.

Default location (via platformdirs, without OS hardcoding):

• Windows: %LOCALAPPDATA%\cvm-mcp

• macOS: ~/Library/Caches/cvm-mcp

• Linux: ~/.cache/cvm-mcp

To use another directory (e.g., restricted environments/CI), set CVM_MCP_CACHE_DIR before running the server.

Important limitations

• Q4 is derived, not published. The CVM does not disclose the 4th quarter separately; the value comes from ano cheio − acumulado 9M. It matches the fiscal year by construction, but it is not a number the company reported.

• No calculated indicators. This version returns published accounting accounts, not margins, ROE, or EBITDA. The indicator code remains in the repository (indicators.py, accounts.py), not linked to any tool, to be readapted to the quarterly base later.

• No market data: the CVM does not publish stock prices, market value, or multiples (P/E, EV/EBITDA). Requests of this type are outside the scope of this source.

• Stock accounts do not add up. BPA and BPP are balances: adding up the 4 quarters of equity produces nothing meaningful. Only flow accounts can be accumulated over 12 months.

• Not every company has 4 quarters (recent IPO, suspension, registration cancellation, late ITR filing). The window returns the periods that exist, without filling gaps with zero.

• Financial sector companies use a different DRE chart of accounts, so the accounting codes are not comparable line by line with those of non-financial companies.

Development

python -m venv .venv
.venv\Scripts\Activate.ps1   # ou source .venv/bin/activate
pip install -e .
python -m cvm_mcp            # roda o servidor via stdio

Project structure:

src/cvm_mcp/
  config.py       # constantes e diretório de cache (cross-platform)
  cache.py        # download HTTP com cache condicional + extração de ZIP
  parsers.py      # leitura dos CSVs (encoding/separador da CVM)
  cvm_client.py   # busca de empresas e carregamento dos demonstrativos
  quarters.py     # montagem da janela trimestral e derivação do 4T
  models.py       # estruturas de dados (Company, Quarter)
  server.py       # servidor MCP (FastMCP) e definição das tools

  accounts.py     # (inativo) mapa do plano de contas -> itens financeiros
  indicators.py   # (inativo) cálculo de indicadores em base anual

accounts.py and indicators.py are not imported by any tool in this version — they remain in the repository to serve as a base when indicators are reintroduced on a quarterly basis.