cvm-mcp

Servidor MCP que busca y procesa datos financieros directamente del Portal de Datos Abiertos de la CVM (dados.cvm.gov.br), sin depender de terceros. Expone herramientas para que un cliente LLM (Claude Desktop, Claude Code, etc.) consulte los estados financieros publicados por las compañías abiertas.

La visión predeterminada es trimestral: las herramientas parten del último trimestre que la empresa publicó y devuelven los 12 meses anteriores, trimestre a trimestre, con las cuentas contables tal como la CVM las publica — sin indicadores calculados.

Lo que hace

Todos los valores monetarios se normalizan a R$ millones. Consulte Limitaciones a continuación — la IA siempre recibe advertencias cuando un dato es derivado o no pudo obtenerse.

Related MCP server: FinancialReports MCP Server

Cómo se compone el trimestre

El ITR de la CVM publica solo 1T, 2T y 3T, y ya trae cada trimestre aislado además de los acumulados del ejercicio — por lo que recortar un trimestre es filtrar período, no restar.

El 4T no existe en el ITR. Se deriva como ejercicio completo (DFP) − acumulado hasta el 3T (ITR), casado cuenta a cuenta por el código contable. Todo período así viene marcado con derivado: true en la respuesta, junto con una advertencia explícita.

Dos consecuencias que vale la pena entender:

• Las cuentas de stock nunca se derivan. BPA y BPP son saldos en una fecha, por lo que el cierre del ejercicio ya es el valor del 4T. Solo las cuentas de flujo (DRE, DFC, DVA, DRA, DMPL) pasan por la resta.

• El "último trimestre" es por empresa, no global. Ejercicios sociales no calendario cierran en otros meses — Camil, por ejemplo, tiene trimestres mar–may, jun–ago, sep–nov y dic–feb. El servidor resuelve esto por las fechas de cada compañía, y la etiqueta (2T26) siempre viene acompañada de inicio y fin.

Instalación

Requiere Python 3.10+. Funciona de la misma forma en Windows, macOS y Linux.

Opción 1 — pipx (recomendado, aísla el entorno)

pipx install .

Se ejecuta en cualquier carpeta después, como el comando cvm-mcp.

Opción 2 — pip en entorno virtual

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

pip install -e .

Opción 3 — directamente desde el código fuente, sin instalar

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

Configurando en Claude Desktop

Edite claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json; macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) y agregue:

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

Si prefiere no instalar con pipx (Opción 3), use:

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

Caché local

Los archivos descargados de la CVM (registro + ZIPs anuales de ITR y DFP) se almacenan en caché local para no descargar de nuevo en cada consulta — la verificación usa ETag/Last-Modified, por lo que las actualizaciones en el portal de la CVM se detectan automáticamente.

Vale la pena dimensionar: los paquetes vienen comprimidos (~20–30 MB por año), pero se extraen para su uso, y cada año-tipo ocupa unos cientos de MB en disco. La vista trimestral suele tocar dos años de ITR más uno de DFP.

Ubicación predeterminada (vía platformdirs, sin hardcode de SO):

• Windows: %LOCALAPPDATA%\cvm-mcp

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

• Linux: ~/.cache/cvm-mcp

Para usar otro directorio (ej: entornos restringidos/CI), defina CVM_MCP_CACHE_DIR antes de ejecutar el servidor.

Limitaciones importantes

• El 4T es derivado, no publicado. La CVM no divulga el 4º trimestre de forma aislada; el valor proviene de año completo − acumulado 9M. Coincide con el ejercicio por construcción, pero no es un número que la empresa reportó.

• Sin indicadores calculados. Esta versión devuelve cuentas contables publicadas, no márgenes, ROE o EBITDA. El código de indicadores continúa en el repositorio (indicators.py, accounts.py), sin estar vinculado a ninguna herramienta, para ser readaptado a la base trimestral después.

• Sin dato de mercado: la CVM no publica cotización, valor de mercado o múltiplos (P/L, EV/EBITDA). Solicitudes de este tipo quedan fuera del alcance de esta fuente.

• Las cuentas de stock no se suman. BPA y BPP son saldos: sumar los 4 trimestres de patrimonio neto no produce nada con significado. Solo las cuentas de flujo pueden acumularse en 12 meses.

• No toda empresa tiene 4 trimestres (IPO reciente, suspensión, cancelación de registro, retraso en la entrega del ITR). La ventana devuelve los períodos que existan, sin llenar el vacío con cero.

• Empresas del sector financiero usan un plan de cuentas de DRE diferente, por lo que los códigos contables no son comparables línea a línea con los de empresas no financieras.

Desarrollo

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

Estructura del proyecto:

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 y indicators.py no son importados por ninguna herramienta en esta versión — quedan en el repositorio para servir de base cuando los indicadores sean reintroducidos en base trimestral.