# Ayuntamiento de Madrid MCP

> Ayuntamiento de Madrid (CKAN) MCP connects directly to the official open data portal of the Madrid City Council. Use this connector to search, categorize, and retrieve metadata for thousands of public datasets covering everything from city transport and environmental reports to municipal budgets. You can list all available packages or drill down into specific resources using natural language queries.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** open-data, municipal-data, ckan-api, public-records, city-services, data-querying

## Description

This MCP lets you query Madrid’s massive open data collection without needing to visit the official website. Instead, you ask your AI client questions about city services, and it finds the right datasets for you. Need to know what departments publish data? You can list all municipal organizations. Want details on a specific dataset's license or update frequency? It pulls that metadata instantly. Whether you’re analyzing air quality trends or tracking public transport usage, this tool provides real-time access to city records. By connecting through Vinkius, you gain immediate access to the entire catalog of Madrid's publicly available information, allowing your agent to perform complex data discovery and resource identification right where you are working.

## Tools

### madrid_get_package
Retrieves the complete technical metadata for a single specified dataset package.

### madrid_get_resource
Fetches the detailed metadata for one specific file or resource within a dataset.

### madrid_list_groups
Lists all major categories or groups of data available in the catalog.

### madrid_list_organizations
Provides a list of all municipal departments that publish open data to the portal.

### madrid_list_packages
Generates a simple list of every available dataset name in the entire catalog.

### madrid_search_packages
Searches for specific datasets, supporting filtering by groups and tags using a query string.

### madrid_search_resources
Allows searching across resources based on defined criteria to find specific files.

### madrid_list_tags
Lists all current tags or keywords used to categorize data across the city’s records.

## Prompt Examples

**Prompt:** 
```
Search for datasets related to 'BiciMAD' in Madrid.
```

**Response:** 
```
I found several datasets related to BiciMAD. The most relevant ones are 'BiciMAD: Estaciones y ocupación' and 'BiciMAD: Uso del servicio'. Would you like the details for one of these?
```

**Prompt:** 
```
List all municipal organizations that publish open data.
```

**Response:** 
```
I've retrieved the list of organizations. There are over 50 departments, including 'Área de Gobierno de Medio Ambiente y Movilidad', 'EMT Madrid', and 'Cultura y Turismo'.
```

**Prompt:** 
```
Get the metadata for the dataset 'puntos-muestreo-aire'.
```

**Response:** 
```
Inspecting 'puntos-muestreo-aire'... This dataset contains the air quality monitoring points in Madrid. It includes 4 resources in CSV and XML formats, maintained by the Environment Department.
```

## Capabilities

### Discover all datasets
List every package or search for groups using keywords like 'environment' or 'transport'.

### Examine dataset metadata
Retrieve deep details on any specific dataset, including its maintainer and usage license.

### Identify and check files
Find individual files (like CSV or JSON) within a dataset and get their specific resource metadata.

### Map city departments
List all municipal organizations that contribute data to the portal, helping you trace information sources.

## Use Cases

### Analyzing air quality changes over time
An environmental researcher needs to track pollution levels across different Madrid districts. They ask their agent to find datasets by calling `madrid_search_packages` with 'air quality' and then use `madrid_get_package` on the result to confirm the data fields match their study criteria.

### Integrating city budget data into a dashboard
A developer must pull financial records for an application. Instead of navigating complex forms, they use `madrid_list_organizations` to find the 'Finance Department' and then search for packages using that source identifier.

### Checking resource availability for a report
A journalist needs data on bike-share usage. They first call `madrid_search_packages` for 'BiciMAD', and then use `madrid_get_resource` to confirm the existence and format of the most recent usage log file.

## Benefits

- Pinpoint exact datasets: Use `madrid_search_packages` to filter thousands of records by topic (e.g., transport, environment), saving hours of manual browsing time.
- Trace data sources: The `madrid_list_organizations` tool tells you exactly which city department maintains the information, crucial for citation and reliability checks.
- Deep metadata access: Instead of just seeing a file name, use `madrid_get_package` to get full context on dataset ownership, update frequency, and licensing requirements.
- Resource precision: Need a specific CSV? Use `madrid_search_resources` or `madrid_get_resource` to identify the exact file metadata, bypassing general searches entirely.
- Understand categorization: List all available groups with `madrid_list_groups` to understand how the city structured its data before you even begin querying.

## How It Works

The bottom line is you get structured access to Madrid’s public information that would otherwise require manual searching across multiple web pages.

1. Subscribe to this MCP and enter your API Key from the Madrid Data portal (if required for certain endpoints).
2. Direct your AI client to use the `madrid_search_packages` or `madrid_list_groups` tool, specifying the city data query.
3. Your agent returns a list of datasets, metadata details, or resource IDs based on the API's live response.

## Frequently Asked Questions

**How do I find datasets related to 'transport' using madrid_search_packages?**
You must use `madrid_search_packages` and specify that filter. You can pass in the group name or relevant tags alongside your query to narrow down results effectively.

**What is the difference between madrid_get_package and madrid_get_resource?**
The `madrid_get_package` tool gives you details about the whole dataset container. The `madrid_get_resource` tool only provides metadata for a single file—like a specific CSV or JSON sheet—within that package.

**Can I find which departments publish data using madrid_list_organizations?**
Yes. Running `madrid_list_organizations` gives you the definitive list of municipal departments, allowing you to map data sources by their source agency name.

**Do I need an API key for madrid_search_packages?**
While some endpoints require keys, your agent handles the authentication process. Always check the documentation if specific endpoints fail; sometimes a key is needed to run searches against certain restricted datasets.

**How do I use madrid_list_tags when I don't know what specific topic I need?**
madrid_list_tags returns a comprehensive list of all keywords used across the portal. You can review these tags to narrow down your research before running a targeted query.

**If I only have a resource ID, how does madrid_get_resource help me inspect that specific file's metadata?**
You provide the unique resource ID directly. The tool then fetches all associated details for that single file or data asset without needing to know which larger dataset it belongs to.

**What is the difference between using madrid_list_packages and searching with madrid_search_packages?**
madrid_list_packages gives you a full inventory of every single available dataset name. Using madrid_search_packages, however, lets you filter that inventory based on criteria like tags or groups.

**When should I use madrid_list_groups versus listing all packages with madrid_list_packages?**
Use madrid_list_groups when you need to browse data by a major municipal division. Use madrid_list_packages if you want an absolute, raw list of every dataset available in the system.

**How can I find datasets specifically about air quality or pollution?**
You can use the `search_packages` tool with a query like 'aire' or 'contaminacion'. The agent will return a list of matching datasets available in the Madrid portal.

**Can I get the direct download link for a data file?**
Yes. By using `get_package` or `get_resource`, the agent will provide the metadata which includes the 'url' field for the specific resources (CSV, PDF, etc.) associated with that dataset.

**How do I see which municipal department published a certain dataset?**
Use the `get_package` tool for a specific dataset ID. The metadata returned will include the organization name. You can also use `list_organizations` to see all publishing entities.