Skip to main content
Glama
deenesjakoptruzh
IgormCarvalho

cvm-mcp

by IgormCarvalho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

cvm-mcp

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

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

功能

工具

使用场景

buscar_empresa

在进行任何分析之前，先解析公司名称/CNPJ/CVM 代码

analisar_empresa

一般性请求（"分析公司 X"）—— 最近 4 个季度的损益表

obter_demonstrativo_trimestral

其他报表（资产负债表、现金流量表）或超过 4 个季度

obter_demonstrativo_anual

当用户明确要求已结束的会计年度（DFP）

所有货币值均归一化为百万雷亚尔。请参阅下面的重要限制——当数据是衍生数据或无法获取时，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 在此版本中未被任何工具导入——它们保留在存储库中，作为日后在季度基础上重新引入指标时的基础。

Available Tools

4 tools
analisar_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.

ParametersJSON Schema
NameRequiredDescriptionDefault
nome_ou_cnpjYes

TDQS

A4.7/5.0
Behavior5/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limiteNo
consultaYes

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
anoYes
consolidadoNo
nome_ou_cnpjYes
demonstrativoYes

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
ano_fimYes
ano_inicioYes
consolidadoNo
nome_ou_cnpjYes

TDQS

A3.9/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters2/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

  1. 4 tool updatesv0.1.0
    • First observedanalisar_empresa
    • First observedbuscar_empresa
    • First observedobter_demonstrativo_bruto
    • First observedobter_indicadores
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 4 tools

Disambiguation5/5

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.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in Portuguese (e.g., analisar_empresa, buscar_empresa). The naming is predictable and clear.

Tool Count5/5

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.

Completeness4/5

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

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

  • GloomB
    sh.gloom.api

    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.

    FinanceResearch & Data
    701
  • Backtest360A
    com.backtest360

    MCP server exposing the Backtest360 engine API as tools for AI agents.

    FinanceResearch & Data
    202
  • AIsa EquitiesAOAuth
    one.aisa

    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.

    FinanceResearch & Data
    261
  • AIsa FinanceAOAuth
    one.aisa

    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.

    CryptocurrencyFinance
    541

Related MCP Servers

  • mcp-brasil

    bob-reis
    A
    license
    A
    quality
    D
    maintenance
    MCP 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.
    6
    MIT

  • FinancialReports MCP Server

    financial-reports
    A
    license
    Not graded
    quality
    B
    maintenance
    Official 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.
    2
    MIT

  • financial-data-mcp-server

    fifah123
    A
    license
    Not graded
    quality
    C
    maintenance
    An 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