# CNMC MCP

> CNMC (Comisión Nacional de los Mercados y la Competencia) provides direct access to Spanish public market data. Use this MCP to search, filter, and retrieve official records across major sectors like energy, telecommunications, transport, and postal services. It lets your agent pull structured statistics directly from the CNMC open data portal without manual CSV downloads.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** spain, market-regulation, open-data, energy-data, telecom-data

## Description

Need market stats for Spain? This connector gives your AI client direct access to the CNMC's public data catalog. You can stop spending hours navigating government websites or downloading massive, disorganized spreadsheets. Instead, you tell your agent what you need—like 'total natural gas consumption in 2022'—and it handles the complex search logic itself. The MCP lets your agent perform two critical steps: first, it finds the specific dataset ID using keywords; second, it pulls only the exact records and rows you requested from that resource. This means whether you're running competitive analysis or writing a regulatory report, you get clean, filtered data right back to your chat window. It’s built into Vinkius, so once you connect your agent, you gain access to this specific Spanish market data alongside thousands of others. You just point it at the problem, and it pulls the numbers.

## Tools

### datastore_search
Retrieves actual records from a specific CNMC resource ID that you already found.

### package_search
Searches the entire CNMC catalog using keywords to find relevant datasets and resources.

## Prompt Examples

**Prompt:** 
```
Search for datasets related to 'energía eléctrica' in the CNMC catalog.
```

**Response:** 
```
I found several datasets. The most relevant one is 'Estadística mensual de energía eléctrica' with resource ID 'e123-abc'. Would you like me to fetch the latest records from it?
```

**Prompt:** 
```
Get the first 5 records from the CNMC resource '06935639-5561-4608-9580-59367208479e'.
```

**Response:** 
```
I've retrieved the first 5 records for that resource. They include data on market shares for telecommunications operators in Q1 2023. [Data table displayed...]
```

**Prompt:** 
```
Search for 'gas natural' datasets and filter the results for the year 2022.
```

**Response:** 
```
I've identified the 'Consumo de gas natural' dataset. Applying the filter for 2022... I found 12 monthly records. Would you like a summary of the total consumption?
```

## Capabilities

### Find available datasets
Search the CNMC catalog using general keywords or queries to find relevant data packages.

### Filter records by criteria
Narrow down large datasets, pulling only rows matching specific dates, regions, or categories.

### Extract raw market statistics
Retrieve actual structured data records from a specified resource ID.

## Use Cases

### Comparing energy consumption across years
A researcher needs to compare natural gas usage from 2019 vs. 2022. Instead of downloading two massive files, they ask the agent to search for 'natural gas' using `package_search`, get the resource ID, and then use `datastore_search` with a filter for both years in one query.

### Checking telecom market share changes
A compliance analyst needs to track how market shares changed across regions. They prompt the agent, asking it to find 'telecom' datasets and apply JSON filters specifically for region codes (e.g., Madrid) and Q2 records.

### Building a report on transport trends
A data analyst wants general stats on rail travel. They use `package_search` to locate the primary 'transport' dataset, then execute `datastore_search` to pull only the records related to passenger volume and specific years.

## Benefits

- Stop manual CSV downloads. Instead of clicking through multiple government portals, the `package_search` tool finds all relevant datasets using simple keywords.
- Get granular control over your data. You can apply JSON filters to narrow down results by date or region when you use `datastore_search`, keeping your output clean and focused.
- Cover key Spanish sectors easily. The MCP handles market statistics for telecommunications, energy, transport, and postal services—all in one place.
- Save time on data discovery. You don't have to know the exact resource ID; `package_search` helps you find that initial dataset link first.
- Process structured records instantly. The agent pulls raw rows directly into your chat interface, ready for immediate analysis.

## How It Works

The bottom line is: your agent handles the multi-step workflow—discovery, filtering, and extraction—in one go.

1. First, use `package_search` to look through the CNMC catalog. You provide keywords (e.g., 'energy sector') and get back potential datasets and their unique IDs.
2. Second, identify the specific resource ID you need. Then, your agent uses this ID with `datastore_search` to pull the actual records from that data source.
3. Finally, if needed, apply JSON filters during the search process. This limits the results so you only get data for a specific region or year.

## Frequently Asked Questions

**How do I find the resource_id needed for data retrieval?**
Use the `package_search` tool with a query related to your topic. The response will include a list of resources, each with a unique `id` (the resource_id) that you can then use in `datastore_search`.

**Can I limit the number of records returned to avoid large payloads?**
Yes! The `datastore_search` tool includes an optional `limit` parameter. You can specify exactly how many rows you want to retrieve (e.g., 10 or 100) to keep the response concise.

**Is it possible to filter data by a specific field, like a year or a city?**
Absolutely. Use the `filters` parameter in `datastore_search`. It accepts a JSON string (e.g., `{"Year": "2023"}`) to return only the records that match your criteria.

**When running `datastore_search`, do I need to manage my rate limits or API credentials?**
Yes, while initial queries are fine, sustained high-volume retrieval requires an API key. Your agent must use this key for `datastore_search` to maintain consistent access and prevent throttling errors.

**If I run `datastore_search` and get an error, should I first re-run `package_search`?**
Absolutely. If the data retrieval fails, the issue is often with the resource ID. Use `package_search` again to verify that you have the correct, current unique identifier for your target dataset.

**Does `package_search` allow me to look up datasets outside of telecommunications or energy sectors?**
The catalog covers multiple domains within Spanish market regulation. Use `package_search` with broader keywords to locate resources related to transport, postal services, and other relevant economic areas.

**What is the expected format when I successfully execute a query using `datastore_search`?**
The data retrieved from `datastore_search` comes in structured records. Your agent will process these rows, making them ready for immediate analysis or further filtering within your client environment.

**What is the proper workflow when using `package_search` before attempting any data pulls?**
The first step must always be to run `package_search`. This locates the specific dataset and provides the required unique resource ID, which you then feed into `datastore_search` for actual records.