# CVM Dados Abertos MCP

> CVM Dados Abertos gives you direct access to Brazil's capital markets data from the CVM Open Data portal. Your agent queries investment funds, listed companies, and financial reports without needing to navigate complex web directories or download files manually. It lets you find specific regulatory filings, inspect dataset metadata, and map out which departments publish what kind of market information.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** capital-markets, investment-funds, financial-reports, open-data, securities-exchange, regulatory-data

## Description

This MCP connects your AI client directly to the Comissão de Valores Mobiliários (CVM) Open Data portal, letting you talk to Brazilian financial data like it’s a natural conversation. Instead of clicking through endless folders or hunting for specific CSV links, your agent handles the deep work. You can ask for all available datasets, check the metadata on any package—like its update frequency or who owns it—and even list which departments manage certain types of filings. When you're building complex market research models, this MCP acts like a direct pipeline to official records. Because Vinkius hosts and manages this connection, you get immediate access across your preferred AI client, letting you spend time analyzing the data instead of figuring out where to find it.

## Tools

### list_groups
Shows thematic groups, like 'Investment Funds,' that categorize financial market information.

### list_organizations
Lists the specific CVM departments responsible for publishing sets of data on the portal.

### list_datasets
Lists every available data package on the CVM portal so you can see all options.

### search_datasets
Searches across all available datasets using keywords to find matching topics or reports.

### get_dataset
Retrieves full metadata for one specific data package on the CVM portal.

### get_resource
Gets metadata and file details for a single, downloadable resource within a dataset.

## Prompt Examples

**Prompt:** 
```
List all datasets available on the CVM portal.
```

**Response:** 
```
I have retrieved the list of available datasets. There are over 50 packages including 'Companhias Abertas', 'Fundos de Investimento', and 'Ofertas Públicas'. Which category interests you?
```

**Prompt:** 
```
Search for datasets related to 'fundos'.
```

**Response:** 
```
Searching for 'fundos'... I found several matches: 'fi-cad' (Registration), 'fi-doc-eventual' (Occasional docs), and 'fi-doc-infodiario' (Daily info). Would you like to see the details for 'fi-cad'?
```

**Prompt:** 
```
Get the metadata for the dataset 'fi-cad'.
```

**Response:** 
```
I've retrieved the metadata for 'fi-cad'. It contains registration information for investment funds and includes 12 resources (CSV files). Would you like the download link for the most recent file?
```

## Capabilities

### Find all available datasets
The agent lists every dataset package available on the CVM portal so you can see what’s in scope.

### Search for specific data topics
You can narrow down the massive catalog by searching keywords, like 'fundos' or 'companhias'.

### Get detailed dataset metadata
The tool fetches complete details on a package, including its tags and ownership information.

### Identify publishing organizations
List the specific CVM departments or groups responsible for creating certain sets of financial data.

### Retrieve resource links
The agent gets direct metadata and download details (CSV, XML) for a specific file within a dataset.

## Use Cases

### A compliance officer needs to audit regulatory filings.
They ask their agent to run `list_organizations` first, identifying which department published the necessary reports. Then they use that information with `search_datasets` to find all relevant documents for a specific company.

### A financial analyst is researching fund performance.
Instead of downloading dozens of PDFs, they ask their agent to run `get_dataset` on 'Investment Funds' and then use the metadata to get direct resource links via `get_resource`, feeding structured data into a spreadsheet.

### A data scientist needs to understand all available market types.
They start by using `list_groups` to categorize the whole market, then use that context to run `search_datasets` for 'Companhias Abertas' to ensure they haven't missed any major data sources.

### A researcher needs a quick overview of all available data types.
They simply ask the agent to use `list_datasets`, immediately seeing packages like 'fi-cad' and 'infodiario,' giving them a map of every possible data source in one step.

## Benefits

- Instead of clicking through directories to find registration files, you can use `search_datasets` to pinpoint specific filings for investment funds instantly. This saves hours of manual searching.
- You don't have to guess what data exists. Use `list_datasets` first; it gives you a full list of every available package on the CVM portal at a glance.
- Need to know who published the data? Use `list_organizations` to map out which specific CVM departments are responsible for certain sets, helping with compliance verification.
- When you find a dataset name using `get_dataset`, you can immediately follow up by calling `get_resource` to get direct links and metadata for the actual CSV or XML files ready for download.
- This MCP helps Data Scientists automate discovery. You can list all relevant groups via `list_groups` before targeting the specific resources, building a reliable data pipeline.

## How It Works

The bottom line is that you skip the web browsing entirely and get structured data results directly in your workflow.

1. Subscribe to the MCP and provide your CVM API Key. This connects your AI client to the data source.
2. Tell your agent exactly what you need—for example, 'List all datasets related to investment funds.'
3. The system finds the relevant package metadata or resource link and hands it back to your chat window for analysis.

## Frequently Asked Questions

**How do I list all available data packages using `list_datasets`?**
You call `list_datasets` with no arguments. This command returns a full inventory, showing you every dataset package on the CVM portal that your agent can access.

**Can I find filings for 'fundos' using `search_datasets`?**
Yes, use `search_datasets` and pass 'fundos' as the query term. The system will return specific dataset names like 'fi-cad,' which you can then investigate further.

**What is the difference between `get_dataset` and `get_resource`?**
`get_dataset` gives you metadata about a whole collection (the container). `get_resource` gets details about one specific file, like its download link or format.

**Do I need an API key for `list_organizations`?**
While the tool can run publicly, providing your CVM API Key is always recommended. It increases your usage limits and makes sure your agent doesn't hit a rate limit during large searches.

**What should I do if `search_datasets` returns zero results for a specific topic?**
The tool indicates no direct match. Check your spelling, or try broadening the search terms. You might need to use `list_groups` first to find the correct thematic area before searching again.

**How do I map a data set back to its originating department using `list_organizations`?**
The system lists all publishing bodies. To narrow it down, you should combine the results from `list_datasets` with specific organizational names you find here.

**If I use `get_dataset`, how do I actually get the download link for a CSV file?**
You must run `get_resource` after getting the metadata. The dataset tells you what data exists, but the resource tool retrieves the direct links and specific file details.

**What happens if I hit rate limits when using multiple tools like `list_datasets`?**
The MCP will return an explicit error code indicating your current limit. For high-volume work, you'll need to manage requests or consider the optional API key for higher usage tiers.

**How can I find the most recent data for a specific investment fund?**
Use the `search_datasets` tool with keywords like 'fundos' or 'fi-cad'. Once you identify the dataset, use `get_dataset` to list all available resources, which typically include the most recent CSV files.

**Can I get the direct download link for a data file?**
Yes! Use the `get_resource` tool with a specific Resource ID. The response will include the `url` field, which is the direct link to the raw data (e.g., a CSV file).

**What are thematic groups in the CVM portal?**
Thematic groups categorize datasets by market segment. Use `list_groups` to see categories like 'Fundos de Investimento', 'Companhias', and 'Auditores Independentes' to better navigate the available data.