cvm-mcp

MCP 服务器，用于直接从 CVM 开放数据门户（dados.cvm.gov.br）搜索和处理财务数据，不依赖第三方。它为 LLM 客户端（Claude Desktop、Claude Code 等）提供工具，用于查询上市公司发布的财务报表。

默认视图为季度：工具从公司发布的最后一个季度开始，返回前 12 个月，按季度划分，包含 CVM 公布的会计科目——不包含计算得出的指标。

功能

所有货币值均归一化为百万雷亚尔。请参阅下面的重要限制——当数据是衍生数据或无法获取时，AI 总是会收到警告。

Related MCP server: FinancialReports MCP Server

季度是如何构建的

CVM 的 ITR 仅发布第 1、2、3 季度，并且除了年度累计值外，它还提供每个单独的季度——因此，截取一个季度是过滤期间，而不是减法。

第 4 季度在 ITR 中不存在。它是通过 完整会计年度 (DFP) − 截至第 3 季度的累计值 (ITR) 得出的，并按会计科目代码逐项匹配。所有此类时期都会在响应中标记为 derivado: true，并附带明确警告。

有两个值得理解的后果：

• 库存科目永远不会是衍生数据。 BPA 和 BPP 是某一日期的余额，因此会计年度末的值就是第 4 季度的值。只有流量科目（损益表、现金流量表、DVA、DRA、DMPL）会进行减法运算。

• "最后一个季度" 是公司级别的，不是全局的。 非日历会计年度在其他月份结束——例如，Camil 的季度是 3-5 月、6-8 月、9-11 月和 12-2 月。服务器根据每家公司的日期解决这个问题，并且标签（2T26）始终附带有 inicio 和 fim。

安装

需要 Python 3.10+。在 Windows、macOS 和 Linux 上工作方式相同。

选项 1 — pipx（推荐，隔离环境）

pipx install .

之后可以在任何文件夹中作为命令 cvm-mcp 运行。

选项 2 — 在虚拟环境中使用 pip

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

pip install -e .

选项 3 — 直接来自源代码，无需安装

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

在 Claude Desktop 中配置

编辑 claude_desktop_config.json（Windows： %APPDATA%\Claude\claude_desktop_config.json；macOS： ~/Library/Application Support/Claude/claude_desktop_config.json）并添加：

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

如果您更喜欢不通过 pipx 安装（选项 3），请使用：

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

本地缓存

从 CVM 下载的文件（注册表 + 年度 ITR 和 DFP ZIP 文件）会缓存在本地，以避免每次查询都重新下载——检查使用 ETag/Last-Modified，因此 CVM 门户的更新会被自动检测到。

需要注意规模：软件包是压缩的（每年约 20-30 MB），但会被解压使用，每种年度类型在磁盘上占用数百 MB。季度视图通常会涉及两年的 ITR 加上一年的 DFP。

默认位置（通过 platformdirs，无硬编码的 OS）：

• Windows：%LOCALAPPDATA%\cvm-mcp

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

• Linux：~/.cache/cvm-mcp

要使用其他目录（例如，受限环境/CI），请在运行服务器之前设置 CVM_MCP_CACHE_DIR。

重要限制

• 第 4 季度是衍生数据，非官方发布。 CVM 不单独公布第 4 季度；其值来自 全年 − 截至 9 个月的累计值。它在结构上与会计年度吻合，但不是公司报告的数字。

• 无计算指标。 此版本返回已发布的会计科目，而不是利润率、ROE 或 EBITDA。指标代码仍保留在存储库中（indicators.py、accounts.py），但未链接到任何工具，以便日后在季度基础上重新调整。

• 无市场数据：CVM 不公布报价、市值或倍数（市盈率、EV/EBITDA）。此类请求不在本数据源的范围内。

• 库存科目不能相加。 BPA 和 BPP 是余额：将 4 个季度的股本相加没有意义。只有流量科目可以累积到 12 个月。

• 并非所有公司都有 4 个季度（近期 IPO、暂停上市、注册注销、ITR 提交延迟）。窗口会返回存在的期间，不会用零填充空缺。

• 金融行业的公司 使用不同的损益表科目表，因此其会计科目代码与非金融公司的无法逐行比较。

开发

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

项目结构：

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 和 indicators.py 在此版本中未被任何工具导入——它们保留在存储库中，作为日后在季度基础上重新引入指标时的基础。