cvm-mcp

MCP 서버로, CVM 오픈 데이터 포털(dados.cvm.gov.br)에서 직접 금융 데이터를 검색하고 처리합니다. 타사에 의존하지 않습니다. LLM 클라이언트(Claude Desktop, Claude Code 등)가 상장 기업이 공개한 재무제표를 조회할 수 있는 도구를 제공합니다.

기본 보기는 분기별입니다: 도구는 기업이 공개한 마지막 분기부터 시작하여 이전 12개월을 분기별로 반환하며, CVM이 공개한 대로 회계 계정을 제공합니다 — 계산된 지표는 없습니다.

기능

모든 금액은 R$ 백만 단위로 정규화됩니다. 아래 중요한 제한 사항을 참조하세요 — AI는 데이터가 파생되었거나 획득할 수 없을 때 항상 경고를 받습니다.

Related MCP server: FinancialReports MCP Server

분기 구성 방식

CVM의 ITR은 1T, 2T, 3T만 공개하며, 각 분기를 별도로 제공할 뿐만 아니라 연간 누계도 함께 제공합니다. 따라서 분기를 분리하는 것은 기간을 필터링하는 것이지 빼기가 아닙니다.

4T는 ITR에 존재하지 않습니다. 이는 전체 회계연도(DFP) − 3분기까지 누계(ITR)로 파생되며, 회계 코드별로 계정을 매칭합니다. 이러한 모든 기간은 응답에 derivado: true로 표시되며 명시적인 경고가 함께 제공됩니다.

이해해야 할 두 가지 결과:

• 재고 계정은 절대 파생되지 않습니다. BPA와 BPP는 특정 날짜의 잔액이므로, 연말 결산이 이미 4분기 값입니다. 흐름 계정(DRE, DFC, DVA, DRA, DMPL)만 빼기 연산을 거칩니다.

• '마지막 분기'는 기업별로 결정되며 전역적이지 않습니다. 역년이 아닌 회계연도를 사용하는 기업은 다른 달에 마감됩니다. 예를 들어 Camil의 분기는 35월, 68월, 911월, 122월입니다. 서버는 각 회사의 날짜를 기준으로 이를 해결하며, 레이블(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~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/L, EV/EBITDA)를 공개하지 않습니다. 이러한 요청은 이 소스의 범위를 벗어납니다.

• 재고 계정은 합산되지 않습니다. BPA와 BPP는 잔액입니다: 4분기의 순자산을 합산해도 의미 있는 값이 나오지 않습니다. 흐름 계정만 12개월로 누적될 수 있습니다.

• 모든 기업이 4분기를 가지는 것은 아닙니다 (최근 IPO, 정지, 등록 취소, ITR 제출 지연). 창은 존재하는 기간만 반환하며, 빈 공간을 0으로 채우지 않습니다.

• 금융 부문 기업은 다른 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는 이 버전에서 어떤 도구에도 임포트되지 않습니다. 지표가 분기별 기준으로 다시 도입될 때 기반이 되도록 저장소에 남아 있습니다.