cvm-mcp

Server MCP, der Finanzdaten direkt vom CVM Open Data Portal (dados.cvm.gov.br) abruft und verarbeitet, ohne auf Dritte angewiesen zu sein. Es stellt Tools für einen LLM-Client (Claude Desktop, Claude Code etc.) bereit, um die von börsennotierten Unternehmen veröffentlichten Finanzberichte abzufragen.

Die Standardansicht ist vierteljährlich: Die Tools gehen vom letzten von einem Unternehmen veröffentlichten Quartal aus und geben die vorherigen 12 Monate, Quartal für Quartal, mit den von der CVM veröffentlichten Konten – ohne berechnete Kennzahlen.

Funktionen

Alle Geldbeträge werden auf Millionen R$ normalisiert. Siehe Einschränkungen unten – die KI erhält immer Hinweise, wenn ein Wert abgeleitet oder nicht ermittelbar ist.

Related MCP server: FinancialReports MCP Server

Wie das Quartal zusammengestellt wird

Das ITR der CVM veröffentlicht nur Q1, Q2 und Q3 und führt jedes Quartal sowohl isoliert als auch als kumulierten Wert des Geschäftsjahres auf – daher wird ein Quartal durch Filtern des Zeitraums ermittelt, nicht durch Subtraktion.

Q4 existiert im ITR nicht. Es wird als vollständiges Geschäftsjahr (DFP) − bis Q3 kumuliert (ITR) abgeleitet, Konto für Konto über den Kontocode abgeglichen. Jeder so ermittelte Zeitraum wird in der Antwort mit derivado: true und einem expliziten Hinweis gekennzeichnet.

Zwei daraus resultierende Konsequenzen, die es zu verstehen gilt:

• Bestandskonten werden nie abgeleitet. BPA und BPP sind Salden zu einem Stichtag, daher ist der Jahresabschluss bereits der Wert für Q4. Nur Flusskonten (DRE, DFC, DVA, DRA, DMPL) werden durch Subtraktion ermittelt.

• Das "letzte Quartal" ist unternehmensspezifisch, nicht global. Geschäftsjahre, die nicht dem Kalenderjahr entsprechen, enden in anderen Monaten – bei Camil beispielsweise sind die Quartale Mär–Mai, Jun–Aug, Sep–Nov und Dez–Feb. Der Server löst dies anhand der Daten des jeweiligen Unternehmens, und die Kennzeichnung (2T26) wird stets von inicio und fim begleitet.

Installation

Erfordert Python 3.10+. Funktioniert gleichermaßen unter Windows, macOS und Linux.

Option 1 — pipx (empfohlen, isolierte Umgebung)

pipx install .

Läuft danach von jedem Ordner aus als Befehl cvm-mcp.

Option 2 — pip in einer virtuellen Umgebung

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

pip install -e .

Option 3 — Direkt aus dem Quellcode, ohne Installation

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

Konfiguration in Claude Desktop

Bearbeiten Sie claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json; macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) und fügen Sie Folgendes hinzu:

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

Wenn Sie die Installation mit pipx bevorzugen (Option 3), verwenden Sie:

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

Lokaler Cache

Die von der CVM heruntergeladenen Dateien (Register + jährliche ZIPs von ITR und DFP) werden lokal zwischengespeichert, um sie nicht bei jeder Abfrage erneut herunterladen zu müssen – die Überprüfung erfolgt über ETag/Last-Modified, sodass Aktualisierungen im CVM-Portal automatisch erkannt werden.

Zur Dimensionierung: Die Pakete kommen komprimiert (~20–30 MB pro Jahr), werden aber zur Nutzung entpackt, und jeder Jahr-Typ belegt einige hundert MB auf der Festplatte. Die vierteljährliche Ansicht betrifft in der Regel zwei Jahre ITR plus ein Jahr DFP.

Standardspeicherort (über platformdirs, ohne hardcodiertes Betriebssystem):

• Windows: %LOCALAPPDATA%\cvm-mcp

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

• Linux: ~/.cache/cvm-mcp

Um ein anderes Verzeichnis zu verwenden (z. B. in eingeschränkten/CI-Umgebungen), setzen Sie CVM_MCP_CACHE_DIR vor dem Start des Servers.

Wichtige Einschränkungen

• Q4 ist abgeleitet, nicht veröffentlicht. Die CVM veröffentlicht das 4. Quartal nicht separat; der Wert stammt aus Gesamtjahr − kumuliert 9 Monate. Es stimmt konstruktionsbedingt mit dem Geschäftsjahr überein, ist aber keine vom Unternehmen gemeldete Zahl.

• Keine berechneten Kennzahlen. Diese Version gibt veröffentlichte Kontosalden zurück, keine Margen, ROE oder EBITDA. Der Code für Kennzahlen bleibt im Repository (indicators.py, accounts.py), ist aber mit keinem Tool verbunden, um später an die vierteljährliche Basis angepasst zu werden.

• Keine Marktdaten: Die CVM veröffentlicht keine Kurse, Marktwerte oder Multiplikatoren (KGV, EV/EBITDA). Derartige Anfragen liegen außerhalb des Rahmens dieser Datenquelle.

• Bestandskonten werden nicht summiert. BPA und BPP sind Salden: Die 4 Quartale des Eigenkapitals zu addieren ergibt nichts Sinnvolles. Nur Flusskonten können über 12 Monate kumuliert werden.

• Nicht jedes Unternehmen hat 4 Quartale (kürzlicher Börsengang, Aussetzung, Löschung der Registrierung, verspätete ITR-Einreichung). Das Fenster gibt die vorhandenen Zeiträume zurück, ohne Lücken mit Nullen zu füllen.

• Unternehmen des Finanzsektors verwenden einen anderen DRE-Kontenplan, sodass die Kontocodes nicht zeilenweise mit denen von Nicht-Finanzunternehmen vergleichbar sind.

Entwicklung

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

Projektstruktur:

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 und indicators.py werden in dieser Version von keinem Tool importiert – sie verbleiben im Repository als Grundlage für die spätere Wiedereinführung von Kennzahlen auf vierteljährlicher Basis.