cvm-mcp

CVMの公開データポータルから直接財務データを取得・処理するMCPサーバーです。サードパーティに依存せず、公開企業が発表した財務諸表をLLMクライアント（Claude Desktop、Claude Codeなど）がツールを通じて照会できるようにします。

標準の表示は四半期ベースです。ツールは企業が最後に発表した四半期から始まり、過去12ヶ月分を四半期ごとに、CVMが公開する勘定科目そのまま（計算指標なし）で返します。

機能

すべての金額は**百万R$**に統一されています。下記の制限事項を参照してください。AIは派生データや取得できなかったデータについて常に警告を受け取ります。

Related MCP server: FinancialReports MCP Server

四半期の構成方法

CVMのITRは第1四半期、第2四半期、第3四半期のみを公開し、各四半期単独の数値に加えて年度累計も提供します。そのため、四半期を切り出すのは期間のフィルタリングであり、減算ではありません。

第4四半期はITRには存在しません。 これは 完全な会計年度（DFP）− 第3四半期までの累計（ITR） として、勘定コードごとに突き合わせて導出されます。このように導出された期間はすべて、応答に derivado: true のフラグと明示的な警告が付与されます。

理解しておくべき2つの結果：

• 在庫勘定は決して導出されません。 BPAおよびBPPは特定日付の残高であるため、会計年度末の値がそのまま第4四半期の値となります。流動勘定（DRE、DFC、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ポータルの更新は自動的に検出されます。

サイズの目安：パッケージは圧縮状態（1年あたり約20～30MB）ですが、使用時に展開され、年・タイプごとに数百MBのディスク容量を消費します。四半期表示では通常、2年分のITRと1年分の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は株価、時価総額、倍率（P/E、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 は、本バージョンではどのツールからもインポートされていません。四半期ベースで指標が再導入される際のベースとしてリポジトリに残されています。