cvm-mcp
cvm-mcp
MCP 서버로, CVM 오픈 데이터 포털(dados.cvm.gov.br)에서 직접 금융 데이터를 검색하고 처리합니다. 타사에 의존하지 않습니다. LLM 클라이언트(Claude Desktop, Claude Code 등)가 상장 기업이 공개한 재무제표를 조회할 수 있는 도구를 제공합니다.
기본 보기는 분기별입니다: 도구는 기업이 공개한 마지막 분기부터 시작하여 이전 12개월을 분기별로 반환하며, CVM이 공개한 대로 회계 계정을 제공합니다 — 계산된 지표는 없습니다.
기능
Tool | 사용 시기 |
| 분석 전에 이름/CNPJ/CVM 코드 확인 |
| 일반 요청('X 회사 분석') — 최근 4분기 DRE |
| 다른 재무제표(대차대조표, 현금흐름표) 또는 4분기 이상 |
| 사용자가 명시적으로 연간 결산(DFP)을 요청할 때 |
모든 금액은 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의 분기는 3
5월, 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_mcpClaude 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-mcpmacOS:
~/Library/Caches/cvm-mcpLinux:
~/.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 anualaccounts.py와 indicators.py는 이 버전에서 어떤 도구에도 임포트되지 않습니다. 지표가 분기별 기준으로 다시 도입될 때 기반이 되도록 저장소에 남아 있습니다.
Available Tools
4 toolsanalisar_empresaA
Análise financeira padrão dos últimos 5 anos de uma empresa.
Use quando o usuário pedir algo genérico como "analise a empresa X" sem especificar período ou indicadores. Retorna, em R$ milhões e por ano: Receita Líquida, EBIT, EBITDA estimado, Lucro Líquido, Margem Líquida, Margem EBITDA, ROE, Liquidez Corrente, Dívida Bruta, Caixa, Dívida Líquida e Dívida Líquida/EBITDA — sempre com avisos quando algum item não pôde ser calculado a partir dos demonstrativos públicos da CVM (ex: EBITDA é sempre uma estimativa, não o número "ajustado" da empresa; não há dado de cotação/valor de mercado nesta fonte). Para pedidos customizados (outro período, dado bruto, individual vs consolidado), use obter_indicadores ou obter_demonstrativo_bruto.
| Name | Required | Description | Default |
|---|---|---|---|
| nome_ou_cnpj | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses key behavioral traits: EBITDA is an estimate, data comes from CVM public filings, no market cap data, and warnings are issued when items cannot be calculated. This fully informs the agent about limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: first sentence states purpose, second guides usage, third lists returns, fourth adds caveats. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, no output schema), the description is complete. It covers what is returned, constraints (5 years), limitations (EBITDA estimate, no market data), and provides usage guidance with alternatives.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description should compensate. The parameter 'nome_ou_cnpj' is self-explanatory, but the description does not elaborate on format or provide examples. It gives context that it's a company identifier, which is adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides a standard financial analysis of the last 5 years of a company, with a specific list of metrics. It distinguishes from siblings by specifying it is for generic requests, while alternatives handle custom periods or raw data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'use when user asks something generic like 'analyze company X' without specifying period or indicators.' It also tells when NOT to use (customized requests) and names alternative tools (obter_indicadores, obter_demonstrativo_bruto).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
buscar_empresaA
Busca companhias abertas no cadastro da CVM por nome, CNPJ ou código CVM.
Use esta tool antes de qualquer outra para confirmar a empresa certa: existem nomes parecidos e empresas com registro cancelado/suspenso que podem não ter demonstrativos recentes.
| Name | Required | Description | Default |
|---|---|---|---|
| limite | No | ||
| consulta | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool searches the CVM registry and that results may include companies with cancelled/suspended status, which is a useful behavioral trait. However, it does not mention any side effects, authentication needs, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main action, and uses line breaks for readability. Every sentence adds value with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with 2 parameters and no output schema or annotations, the description covers purpose, usage guidance, and the main parameter. However, it omits explanation of the 'limite' parameter and return values, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains that 'consulta' can be a name, CNPJ, or CVM code, adding meaning. However, it fails to describe 'limite' (limit), which defaults to 10. Partial compensation leads to a score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (busca = searches), resource (companies in CVM registry), and search criteria (name, CNPJ, or CVM code). It distinguishes from sibling tools like analisar_empresa or obter_indicadores, which are for analysis and data retrieval, not searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use this tool before any other to confirm the correct company, warning about similar names and cancelled/suspended registrations. This provides clear when-to-use and context-specific guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
obter_demonstrativo_brutoA
Devolve as contas contábeis brutas (código, descrição, valor em R$ milhões) de um demonstrativo publicado pela CVM, sem nenhum cálculo.
demonstrativo: um de BPA, BPP, DRE, DFC_MD, DFC_MI, DVA, DMPL, DRA. Use quando o usuário pedir algo que os indicadores prontos não cobrem, como uma conta contábil específica ou maior nível de detalhe.
| Name | Required | Description | Default |
|---|---|---|---|
| ano | Yes | ||
| consolidado | No | ||
| nome_ou_cnpj | Yes | ||
| demonstrativo | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses that the tool returns raw data 'sem nenhum cálculo' (without any calculation), indicating it is a read-only operation. However, it does not mention potential side effects or response size considerations, but the core behavior is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a list, front-loaded with the action ('Devolve as contas contábeis brutas...'). Every sentence adds value, and the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and 3 siblings, the description covers the core functionality, usage context, and return structure (code, description, value). It lacks details on error handling or missing data behavior, but overall it is sufficiently complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 4 parameters with 0% description coverage. The description only adds meaning for the 'demonstrativo' parameter by listing valid values (BPA, BPP, DRE, etc.). Other parameters (nome_ou_cnpj, ano, consolidado) are not explained in the description, leaving their purpose inferred from context. This partially compensates for the schema gap but is insufficient for full clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns raw accounting accounts (code, description, value in BRL millions) from a CVM financial statement, without calculations. It lists specific statement types (BPA, BPP, DRE, etc.) and distinguishes itself from sibling 'obter_indicadores' by noting it provides raw detail when indicators are insufficient.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Use when the user asks for something that the ready indicators don't cover, like a specific accounting account or greater level of detail.' This provides clear guidance and implies alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
obter_indicadoresA
Indicadores financeiros calculados para um intervalo de anos escolhido pelo usuário (mesmos indicadores de analisar_empresa, mas com período e versão consolidado/individual livres). Use para pedidos customizados que fogem do padrão de 5 anos.
| Name | Required | Description | Default |
|---|---|---|---|
| ano_fim | Yes | ||
| ano_inicio | Yes | ||
| consolidado | No | ||
| nome_ou_cnpj | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the tool returns the same indicators as analisar_empresa but with free period and consolidation choice. However, it does not mention any behavioral traits like performance implications, data freshness, or error handling, which are important for a computation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences that front-load the core purpose and usage context. No redundant or extra information is present; every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description is too sparse. It does not explain the returned indicators, parameter details (especially nome_ou_cnpj and consolidado), or error conditions. A user would need additional context to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameter descriptions (0% coverage). The description only partially explains ano_inicio, ano_fim, and consolidado via the phrase 'intervalo de anos' and 'versão consolidado/individual'. It does not clarify consolidado's meaning or the nome_ou_cnpj parameter at all. This is insufficient compensation for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool computes financial indicators for a user-chosen year range, and distinguishes it from sibling analisar_empresa by emphasizing flexibility in period and consolidation version. It uses a specific verb ('calculados') and resource ('indicadores financeiros'), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to use this tool for custom requests that deviate from the standard 5-year period, implying that analisar_empresa should be used otherwise. This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
v0.1.0- First observed
analisar_empresa - First observed
buscar_empresa - First observed
obter_demonstrativo_bruto - First observed
obter_indicadores
TDQS
Scored across 4 tools
Each tool serves a distinct purpose: buscar_empresa for company lookup, analisar_empresa for standard 5-year analysis, obter_indicadores for custom analysis, and obter_demonstrativo_bruto for raw accounting data. No overlap in functionality.
All tool names follow a consistent verb_noun pattern in Portuguese (e.g., analisar_empresa, buscar_empresa). The naming is predictable and clear.
With 4 tools, the server is well-scoped for its domain. It covers company search, standard analysis, custom analysis, and raw data retrieval without unnecessary bloat.
The tool set covers core workflows: identification, standard analysis, custom analysis, and raw data. A minor gap is the absence of a tool for comparing multiple companies or exporting data, but the essential functionality is present.
Maintenance
Related MCP Connectors
Financial data MCP server for Claude, ChatGPT, Cursor and Codex. Real-time stock quotes, financial statements, options flow, SEC filings, insider trades, 13F holdings, macro data and market news from gloom.sh, the open-source Bloomberg Terminal alternative.
MCP server exposing the Backtest360 engine API as tools for AI agents.
Your agent needs company financials it can compute on — statements, ratios, earnings, estimates, filings and insider activity as structured data, not a PDF. **What you can ask for** • "Give me 8 quarters of income statement, balance sheet and cash flow for this ticker." • "What do analysts estimate for next quarter, and how did the last four surprise?" • "Find this exact line item across every filing." • "Who bought or sold as an insider in the last 90 days?" • "Screen for profitable companies under this valuation with growing revenue." **How to use it** Point any MCP client at https://mcp.aisa.one/marketpulse/mcp and sign in with OAuth — there is no key to create or paste. 21 tools: prices and snapshots, income statements, balance sheets, cash-flow statements, financial metrics and snapshots, earnings, analyst estimates, company facts, filings and filing items, line-item search, a screener, insider trades, macro interest rates, news, plus EDINET documents and filing digests for Japanese issuers. **Why this rather than the source** Statements as fields you can compute on, and a screener in the same place. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Read the fundamentals here, then ask the same agent what social is saying about the ticker — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/finance/mcp for equities, crypto and prediction markets in one place.
Your agent needs markets — prices and fundamentals for listed companies, the filings behind them, crypto, and what the prediction markets put the odds at. **What you can ask for** • "Pull this company's income statement, cash flow and balance sheet for the last 8 quarters." • "What did insiders buy or sell, and when?" • "Snapshot prices for these 50 tickers, then the OHLC history for the three that moved." • "What are the current odds on this event across Kalshi and Polymarket?" • "Screen for companies matching these financial criteria." **How to use it** Point any MCP client at https://mcp.aisa.one/finance/mcp and sign in with OAuth — there is no key to create or paste. 49 tools: prices and snapshots, income statements, balance sheets and cash flows, metrics and ratios, earnings and analyst estimates, filings and line-item search, insider trades, macro interest rates, news, a screener; CoinGecko spot prices, market tables, OHLC, per-venue tickers and trending; Kalshi and Polymarket markets and trades; plus EDINET filings for Japan. **Why this rather than the source** Equities, crypto and event markets behind one account, so a cross-asset question is one conversation. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Read the number here, then ask the same agent what X is saying about the ticker today — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/marketpulse/mcp · /crypto-market-data/mcp · /prediction-market-data/mcp · /stock-pulse/mcp for one slice each.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP Server for accessing 36 Brazilian public data sources and 1 agent, enabling AI agents to query government data on economy, legislation, transparency, judiciary, elections, environment, health, and more.6MIT
- AlicenseNot gradedqualityBmaintenanceOfficial MCP server for the FinancialReports API. Provides direct access to regulatory filings, financial data, and corporate information from listed companies worldwide via 15 curated tools.2MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server that exposes real-time financial data tools for stock search, company info, historical prices, and financial metrics from Yahoo Finance, enabling AI agents to answer natural-language questions about stocks and financial markets.MIT
- AlicenseAqualityBmaintenanceMCP server that lets an LLM read official SEC financial data, tracing every number back to a specific SEC filing, US-GAAP tag, and filing date.4MIT