Primeros pasos

En este tutorial harás tu primera petición a la API REST, entenderás qué devuelve y conectarás el servidor MCP a un asistente de IA. No necesitas registrarte ni pedir una clave: la API y el MCP son gratuitos y de solo lectura.

Necesitas: una terminal con curl (o Node.js 18+ o Python 3) y, para la segunda parte, un cliente MCP como Claude, ChatGPT, Cursor, VS Code o Claude Code.

1. Tu primera petición

La API está en https://api.preciosgasolina.es/v1. Pide las 5 gasolineras con el diésel más barato de la provincia de Madrid (código INE 28):

curl "https://api.preciosgasolina.es/v1/stations/cheapest?fuel=diesel&level=province&code=28&limit=5"

const url = new URL("https://api.preciosgasolina.es/v1/stations/cheapest");
url.search = new URLSearchParams({ fuel: "diesel", level: "province", code: "28", limit: "5" });

const res = await fetch(url);
const { data, meta } = await res.json();
console.log(data.stations.map((s) => `${s.price} €/L · ${s.name} (${s.municipality.name})`));
console.log("Datos de", meta.last_updated, "·", meta.attribution);

import requests  # pip install requests

r = requests.get(
    "https://api.preciosgasolina.es/v1/stations/cheapest",
    params={"fuel": "diesel", "level": "province", "code": "28", "limit": 5},
    timeout=10,
)
r.raise_for_status()
body = r.json()
for s in body["data"]["stations"]:
    print(s["price"], "€/L ·", s["name"], f'({s["municipality"]["name"]})')
print("Datos de", body["meta"]["last_updated"], "·", body["meta"]["attribution"])

2. Lee la respuesta

Todas las respuestas correctas tienen la misma forma: un objeto con data (el resultado) y meta (fecha, fuente, licencia y enlace a la web). Así es una respuesta recortada a una gasolinera:

{
  "data": {
    "fuel": "diesel",
    "unit": "L",
    "currency": "EUR",
    "area": {
      "level": "province",
      "code": "28",
      "name": "Madrid",
      "web_url": "https://preciosgasolina.es/precios-gasolineras/comunidad-de-madrid/madrid/"
    },
    "note": null,
    "stations": [
      {
        "id": 12345,
        "name": "Estación de ejemplo",
        "brand": { "slug": "marca-ejemplo", "name": "Marca Ejemplo" },
        "address": "Calle de Ejemplo, 1",
        "postal_code": "28001",
        "municipality": { "id": 4354, "name": "Madrid" },
        "province": { "code": "28", "name": "Madrid" },
        "community": { "code": "13", "name": "Comunidad de Madrid" },
        "lat": 40.39,
        "lng": -3.65,
        "is_24h": true,
        "hours": "L-D: 24H",
        "low_tax_area": false,
        "web_url": "https://preciosgasolina.es/gasolineras/estacion-de-ejemplo-12345/",
        "price": 1.459,
        "price_updated_at": "2026-10-07T06:12:00.000+00:00"
      }
    ]
  },
  "meta": {
    "api_version": "v1",
    "request_id": "8c1f2a9b3d4e5f60",
    "last_updated": "2026-10-07T06:12:00.000Z",
    "next_update": "2026-10-07T18:10:00.000Z",
    "data_age_seconds": 7430,
    "stale": false,
    "source": "Ministerio para la Transición Ecológica y el Reto Demográfico (Geoportal de Gasolineras)",
    "attribution": "Fuente: Gasolina hoy (preciosgasolina.es), con datos del Ministerio para la Transición Ecológica y el Reto Demográfico (Geoportal de Gasolineras).",
    "license": "https://creativecommons.org/licenses/by/4.0/",
    "web_url": "https://preciosgasolina.es/precios-gasolineras/comunidad-de-madrid/madrid/"
  }
}

Fíjate en tres campos de meta:

last_updated: fecha y hora (UTC) de los datos. Los precios se actualizan dos veces al día, hacia las 8:00 y las 20:00 (hora peninsular): no son en tiempo real. Más en Frescura de los datos.
attribution: el texto que debes mostrar junto a los datos (licencia CC BY 4.0). Más en Atribución y licencia.
web_url: la página equivalente de preciosgasolina.es, para enlazarla como fuente.

Los precios van en euros por litro (por kilo con el GNC) y con tres decimales, como los publica el Ministerio. Cada campo está explicado en la referencia.

3. Prueba un error

Pide un carburante que no existe:

curl -i "https://api.preciosgasolina.es/v1/prices?fuel=petrol"

La API responde 400 con un error en formato RFC 9457 (application/problem+json) y un code estable que tu código puede comprobar:

{
  "type": "https://docs.preciosgasolina.es/conceptos/errores/#invalid-parameter",
  "title": "Parámetros no válidos",
  "status": 400,
  "detail": "fuel: Invalid option: expected one of \"gasoline_95\"|\"gasoline_98\"|\"diesel\"|\"diesel_premium\"|\"lpg\"|\"cng\"",
  "code": "INVALID_PARAMETER",
  "request_id": "c51fe0c34cbb42eb",
  "instance": "/v1/prices"
}

La lista de códigos está en Errores.

4. Conecta el servidor MCP

El servidor MCP ofrece los mismos datos a los asistentes de IA. Su dirección es:

https://mcp.preciosgasolina.es/mcp

No hace falta iniciar sesión. Por ejemplo, en Claude Code:

claude mcp add --transport http preciosgasolina https://mcp.preciosgasolina.es/mcp

Añade el servidor en tu cliente (pasos para Claude, ChatGPT, Cursor y VS Code en Conectar el servidor MCP).
Abre un chat nuevo y activa el conector si tu cliente lo pide.
Pregunta, por ejemplo: «¿Qué provincia tiene el diésel más barato hoy?». El asistente usará la herramienta compare_regions y te dará la fecha de los datos y el enlace a preciosgasolina.es.

Siguientes pasos

Conceptos básicosIdentificadores de carburantes, territorios y gasolineras.

GuíasCasos de uso completos, paso a paso.

Herramientas del MCPLas 21 herramientas con sus argumentos.

Referencia de la APIEndpoints, parámetros y cabeceras.

Fuente de los datos: Ministerio para la Transición Ecológica y el Reto Demográfico (Geoportal de Gasolineras). Datos de la API y del servidor MCP con licencia CC BY 4.0: cita Gasolina hoy y la fuente.