cvm-mcp

Сервер MCP, который ищет и обрабатывает финансовые данные напрямую с Портала открытых данных CVM (dados.cvm.gov.br), без зависимости от третьих лиц. Предоставляет инструменты для LLM-клиента (Claude Desktop, Claude Code и т.д.) для запроса финансовой отчётности, опубликованной открытыми компаниями.

Стандартное представление — квартальное: инструменты начинают с последнего квартала, опубликованного компанией, и возвращают предыдущие 12 месяцев, поквартально, с бухгалтерскими счетами, как их публикует CVM — без рассчитанных показателей.

Что он делает

Все денежные значения нормализованы до R$ миллионов. См. Ограничения ниже — ИИ всегда получает предупреждения, когда данные являются производными или не могут быть получены.

Related MCP server: FinancialReports MCP Server

Как формируется квартал

ITR CVM публикует только 1T, 2T и 3T, и уже содержит каждый квартал отдельно, помимо накопленных за год — поэтому выделение квартала — это фильтрация периода, а не вычитание.

4T не существует в ITR. Он выводится как полный год (DFP) − накопленный до 3T (ITR), сопоставленный по счетам с помощью бухгалтерского кода. Каждый такой период помечается как derivado: true в ответе, вместе с явным предупреждением.

Два следствия, которые стоит понять:

• Счета запасов никогда не являются производными. BPA и BPP — это остатки на дату, поэтому закрытие года уже является значением 4T. Только счета потоков (DRE, DFC, DVA, DRA, DMPL) подвергаются вычитанию.

• «Последний квартал» зависит от компании, а не является глобальным. Некалендарные финансовые годы закрываются в другие месяцы — например, у Camil кварталы мар–май, июн–авг, сен–ноя и дек–фев. Сервер решает это по датам каждой компании, и метка (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 файлы (реестр + годовые ZIP-архивы ITR и DFP) сохраняются в локальном кеше, чтобы не загружать их заново при каждом запросе — проверка использует ETag/Last-Modified, поэтому обновления на портале CVM обнаруживаются автоматически.

Стоит учитывать: пакеты поставляются сжатыми (~20–30 МБ в год), но извлекаются для использования, и каждый год-тип занимает несколько сотен МБ на диске. Квартальное представление обычно затрагивает два года ITR плюс один год DFP.

Стандартное расположение (через platformdirs, без жёсткой привязки к ОС):

• Windows: %LOCALAPPDATA%\cvm-mcp

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

• Linux: ~/.cache/cvm-mcp

Чтобы использовать другой каталог (например, в ограниченных средах/CI), установите CVM_MCP_CACHE_DIR перед запуском сервера.

Важные ограничения

• 4T является производным, а не опубликованным. CVM не публикует 4-й квартал отдельно; значение получается из полный год − накопленный 9M. По построению совпадает с годовым отчётом, но это не число, которое сообщила компания.

• Без рассчитанных показателей. Эта версия возвращает опубликованные бухгалтерские счета, а не маржи, ROE или EBITDA. Код показателей остаётся в репозитории (indicators.py, accounts.py), не привязанный ни к одному инструменту, для последующей адаптации к квартальной основе.

• Нет рыночных данных: CVM не публикует котировки, рыночную стоимость или мультипликаторы (P/L, EV/EBITDA). Запросы такого рода выходят за рамки этого источника.

• Счета запасов не суммируются. BPA и BPP — это остатки: суммирование 4 кварталов собственного капитала не даёт ничего осмысленного. Только счета потоков могут накапливаться за 12 месяцев.

• Не у всех компаний есть 4 квартала (недавнее IPO, приостановка, отмена регистрации, задержка с предоставлением ITR). Окно возвращает существующие периоды, не заполняя пробелы нулями.

• Компании финансового сектора используют другой план счетов DRE, поэтому бухгалтерские коды не сравнимы построчно с кодами нефинансовых компаний.

Разработка

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 не импортируются ни одним инструментом в этой версии — они остаются в репозитории, чтобы служить основой, когда показатели будут повторно введены на квартальной основе.