# Murcia Data MCP

> Región de Murcia Datos Abiertos connects your AI client directly to the official open data catalog for the Region of Murcia, Spain. It lets you programmatically query thousands of public datasets, list all contributing government organizations, and search specific regional statistics (like environment or demographics) without navigating a web portal.

## Overview
- **Category:** data-management
- **Price:** Free
- **Tags:** open-data, ckan, public-sector, regional-data, data-catalog, transparency

## Description

You connect your AI client straight into the official open data catalog for the Region of Murcia. This server gives you direct access to thousands of public datasets, letting you query regional stats—everything from environment reports and local economies to population figures—without having to mess around on a web portal.

**Discovery: Finding What You Need**

If you're starting from scratch and just need an overview, you can run `list_datasets` to pull a complete inventory of every single dataset available in the entire catalog. For targeted research, don't worry about manually browsing; you use **`search_datasets`** to search the whole collection using keywords or specific criteria. You want to narrow down the scope? Run **`list_groups`**, and you get all the predefined subject groups—the main categories for data like 'Health' or 'Transportation.' To focus on who published it, run **`list_organizations`**; this spits out a list of every government department or group that contributes data to the site. You can combine these tools: first check **`list_groups`** for broad topics, then use those keywords in **`search_datasets`**.

**Trend Tracking and Dataset Status**

You're trying to figure out what people are actually looking at? Run **`get_most_viewed_datasets`**, and you instantly get the list of datasets that have been accessed most frequently. Need to know what’s fresh? You call **`get_most_recent_datasets`** to pull a roster of everything that was just added to the catalog. These tools let you track data interest, showing you what's popular or what's brand new.

**Deep Dive Metadata Retrieval**

Once you zero in on a specific ID, you don't want guesswork. You need complete details—formats, descriptions, resource links—right away. That’s where **`get_dataset`** comes in. If you feed it a single dataset ID, you get all the metadata and full specifications for that one entry. It's like pulling up the detailed spec sheet on your phone.

**How Your Agent Uses This:**

Your AI client executes these functions directly. You don't build web forms or click through menus. When your agent runs **`search_datasets(query='urban development')`**, for example, the server doesn't just give you a link; it returns structured JSON metadata describing all relevant datasets, who created them, and exactly where they live in the catalog.

If you run **`list_organizations`**, your agent gets back every contributing body. If you follow that up by calling **`get_dataset(id='...')`** for a specific dataset from one of those organizations, you get the complete picture: the origin, the full description, and whether it's formatted as CSV or JSON.

This server lets your agent do everything from listing *all* available datasets with **`list_datasets`**, to finding the top-tier data using **`get_most_viewed_datasets`**, all while keeping the output clean and machine-readable. You're always working off structured JSON, period. You can run **`search_datasets`** for keywords, then use **`list_groups`** to refine those keywords into categories, giving you a layered approach that traditional web browsing just can't match.

## Tools

### get_dataset
Retrieves all metadata and details for a specific dataset ID.

### get_most_recent_datasets
Lists datasets that were most recently added to the catalog.

### get_most_viewed_datasets
Identifies and lists the datasets that have been viewed or accessed most frequently.

### list_datasets
Outputs a list of every single dataset currently available in the entire catalog.

### list_groups
Retrieves all predefined subject groups or categories within the data portal.

### list_organizations
Lists every government organization or group that publishes data on the site.

### search_datasets
Searches the entire catalog for datasets matching specific keywords or criteria.

## Prompt Examples

**Prompt:** 
```
Search for datasets about 'medio ambiente' in the Murcia portal.
```

**Response:** 
```
I found several datasets related to the environment. Notable ones include 'Calidad del aire' and 'Espacios naturales protegidos'. Would you like the details for any of these?
```

**Prompt:** 
```
Show me the 10 most viewed datasets in Murcia.
```

**Response:** 
```
The most viewed datasets include the 'Directorio de Centros Educativos', 'Presupuestos Municipales', and 'Evolución de la población'. I can fetch the full metadata for any of these if you provide the name.
```

**Prompt:** 
```
List all organizations that publish data on the portal.
```

**Response:** 
```
I've retrieved the list of organizations. There are many contributors, including 'Consejería de Salud', 'Ayuntamiento de Murcia', and 'Servicio Murciano de Salud'. Which organization's data are you interested in?
```

## Capabilities

### Search for specific data sets
Find datasets using keywords or filters via the `search_datasets` tool.

### Browse by publishing organization
List all government departments and organizations that contribute data through `list_organizations`.

### Explore data categories
View the full list of predefined subject groups using the `list_groups` tool.

### Check dataset metadata
Pull complete details—formats, descriptions, links—for a single dataset with `get_dataset`.

### Identify data trends
Determine popular or newly added datasets by calling `get_most_viewed_datasets` or `get_most_recent_datasets`.

## Use Cases

### Mapping all contributing agencies
You need a list of every agency that reports on public health in Murcia for a report. Instead of clicking deep into multiple sections, you simply ask the agent to use `list_organizations`. The result is an immediate, structured JSON list of contributors.

### Finding environmental data quickly
A student needs statistics on air quality ('calidad del aire'). They don't know which department has the data. Asking the agent to `search_datasets` for 'medio ambiente' instantly narrows down thousands of results to relevant, actionable datasets.

### Building a dashboard feature
A developer needs to show users the most popular local government spending figures. They call `get_most_viewed_datasets`, get the names like 'Presupuestos Municipales', and build their component around that structured list.

### Tracking data updates
The team needs to know what new economic metrics were added this week. Instead of checking multiple departmental portals, they call `get_most_recent_datasets` to see only the latest additions across the entire region's catalog.

## Benefits

- Structured discovery: Instead of browsing, you call `search_datasets` to filter results by keyword. It's instant and precise.
- Source mapping: Use `list_organizations` to get a clear inventory of every department contributing data—you know exactly who owns the stats.
- Trend awareness: Know what’s hot or new with `get_most_viewed_datasets` and `get_most_recent_datasets`. Don't waste time looking at stale info.
- Deep inspection: When you find a promising dataset, `get_dataset` gives you all the technical details—formats, resource links, everything—in one call.
- Systematic browsing: Need to scope your search? Use `list_groups` first. It lets you walk through the data catalog by official subject area.

## How It Works

The bottom line is that your AI client handles all the API calls; you just talk to it in natural language.

1. Subscribe to the server and (if needed) provide your Murcia API Key.
2. Tell your AI agent exactly what data you need. For example, 'Search for environment datasets published by the health service.'
3. The agent uses tools like `list_organizations`, then `search_datasets`, and finally `get_dataset` to return structured metadata.

## Frequently Asked Questions

**How do I search for data on a specific topic using `search_datasets`?**
`search_datasets` takes a keyword (like 'medio ambiente') and returns all matching datasets. It's much better than browsing because you don't have to guess which category the data lives in.

**Do I need `list_organizations` before I can search for anything?**
No, but it helps define your scope. You can run `search_datasets` immediately. However, if you want to limit results only to the 'Health Department,' running `list_organizations` first and passing that name to the agent gives you better control.

**What's the difference between `list_groups` and `search_datasets`?**
`list_groups` only shows the official, high-level categories (like 'Environment'). `search_datasets`, however, lets you use specific keywords ('calidad del aire') to find data that might not fit into a standard group.

**How do I check if a dataset is current using `get_most_recent_datasets`?**
`get_most_recent_datasets` shows the metadata for datasets that were recently added to the catalog. This tells you about new information, not necessarily data that was just updated.

**If I exceed my API quota while running `get_dataset`, what happens?**
The system returns an HTTP 429 error. This means you hit the rate limit for the specified timeframe, and you need to wait before retrying the call. Using the dedicated Murcia API Key helps manage these limits.

**Does `get_dataset` provide enough detail to know if I can download the data?**
Yes, it retrieves comprehensive metadata, including the required file format and direct resource links for the dataset. You'll find all the necessary paths there.

**When I use `list_datasets`, what kind of domain information do I get for each entry?**
It returns a list containing basic identifiers, titles, and general subject categories. This helps you quickly gauge if the dataset falls within your desired field like environment or economy.

**Can `search_datasets` filter results by a specific group name for better accuracy?**
Yes, passing the organization's identifier during the search narrows down results significantly. This is much more precise than simply searching keywords across all available datasets.

**How can I find datasets related to a specific topic like 'transport'?**
You can use the `search_datasets` tool. Just provide a query string like 'transporte' and the agent will return all matching packages from the Murcia portal.

**Can I see which public data is currently trending or most popular?**
Yes! Use the `get_most_viewed_datasets` tool to retrieve the ten most visited datasets in the portal, or `get_most_recent_datasets` for the latest additions.

**How do I get the full details and download links for a specific dataset?**
Use the `get_dataset` tool with the dataset's ID or name. It will provide complete metadata, including descriptions of the resources and their access URLs.