Skip to main content
Glama

gasolineras-mcp

Este proyecto tiene por objetivo enseñarte a conectar tu LLM (IA) a datos públicos y utilizarlos. Hemos utilizado los precios de las gasolineras en España por su sencillez y utilidad. El Ministerio publica una API con datos públicos. El MCP simplemente facilita el uso de la API en tu LLM.

No es un paso imprescindible si tu IA tiene acceso a una terminal (como Claude Code), pero es la única vía en clientes como Claude Desktop. Y sienta los principios para tareas más complejas, como conectar en el futuro la IA con tus finanzas, tus documentos, etc.

Qué es "instalar un MCP"

Un MCP local no se instala en ningún sitio central: es un programa que tu cliente (Claude Desktop, Claude Code) arranca por debajo y con el que habla. Instalarlo son siempre dos pasos:

  1. Tener el programa en tu máquina.

  2. Decirle al cliente qué comando ejecutar para arrancarlo.

Related MCP server: GasBuddy MCP Price Tracker

Vía rápida (recomendada): uvx

Con uvx los dos pasos casi se funden: el propio comando descarga el paquete de PyPI y lo ejecuta, así que no instalas nada a mano.

Paso 1 — instala uv (una sola vez, vale para cualquier MCP en Python):

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

En Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Paso 2 — díselo a tu cliente.

Claude Code (terminal):

claude mcp add -s user gasolineras -- uvx gasolineras-mcp

El -s user importa: sin él, el servidor solo existe para la carpeta desde la que ejecutes el comando, y en cualquier otra Claude no lo verá — ni te avisará de que le falta.

Claude Desktop: añade esto a tu claude_desktop_config.json (Ajustes → Desarrollador → Editar configuración) y reinicia la app:

{
  "mcpServers": {
    "gasolineras": {
      "command": "uvx",
      "args": ["gasolineras-mcp"]
    }
  }
}

Si Claude Desktop dice que no encuentra uvx (pasa sobre todo en macOS: las apps de escritorio no ven el mismo PATH que tu terminal), pon la ruta completa en "command" — normalmente /Users/<tu-usuario>/.local/bin/uvx (en Linux, /home/<tu-usuario>/.local/bin/uvx).

Codex CLI (OpenAI):

codex mcp add gasolineras -- uvx gasolineras-mcp

Gemini CLI (Google):

gemini mcp add -s user gasolineras uvx gasolineras-mcp

opencode: añade esto a tu opencode.json:

{
  "mcp": {
    "gasolineras": {
      "type": "local",
      "command": ["uvx", "gasolineras-mcp"]
    }
  }
}

Cualquier otro cliente compatible con MCP funciona igual: el comando es uvx con el argumento gasolineras-mcp.

Vía pedagógica: clonar el repo y montarlo tú

Es lo mismo, pero haciendo tú el paso 1 a mano — útil para entender qué hay dentro. Necesitas Python 3.10 o superior.

git clone https://github.com/gregoriofraile/gasolineras-mcp
cd gasolineras-mcp
python3 -m venv .venv
.venv/bin/pip install .

Esto deja el ejecutable en .venv/bin/gasolineras-mcp dentro de la carpeta del proyecto. El paso 2 es igual que arriba, sustituyendo uvx gasolineras-mcp (o el "command" del JSON) por la ruta completa a ese ejecutable.

Comprueba que funciona de verdad

Cuidado: si el MCP no está bien registrado, la IA no avisa — responde con lo que tiene (o se lo inventa) y parece que funciona. Para verificar:

  1. Lista los servidores registrados: claude mcp list, codex mcp list o gemini mcp list, según tu cliente. Debe salir gasolineras conectado.

  2. Abre una sesión nueva (las abiertas no cargan MCPs nuevos).

  3. Pregunta, por ejemplo: "¿Dónde está la gasolina más barata de Teruel?" — en la respuesta debe verse la llamada a la herramienta precios_carburantes (MCP).

Licencia

MIT. Los datos son públicos, del Ministerio para la Transición Ecológica (API de precios de carburantes). Este proyecto no guarda nada tuyo: ni claves, ni datos personales, ni telemetría.


English: MCP server (stdio, Python) for fuel prices at any gas station in Spain, using the Spanish government's public API (no key required). Two tools: buscar_municipio (find a municipality) and precios_carburantes (stations sorted by price). Install: uvx gasolineras-mcp. No state, no keys, no telemetry.

Available Tools

2 tools
buscar_municipioA

Busca municipios españoles por nombre para obtener su ID.

El ID de municipio hace falta para llamar a precios_carburantes. La búsqueda es por tokens (no requiere escribir el nombre exacto ni en el orden exacto): "El Bonillo" encuentra "Bonillo (El)", "Kanpezu" encuentra el municipio bilingüe "Campezo/Kanpezu". Devuelve siempre la provincia porque hay nombres de municipio repetidos entre provincias (p. ej. tres municipios llamados "Boadilla").

Args: nombre: nombre o parte del nombre del municipio a buscar.

Returns: Lista de coincidencias, cada una con id, municipio y provincia. Lista vacía si no hay ninguna coincidencia.

Inputs: nombre (required). Returns: result

precios_carburantesA

Precios de un carburante en las gasolineras de un municipio.

Usa el ID de municipio que devuelve buscar_municipio. El resultado viene ordenado de más barata a más cara. Las gasolineras que no venden el producto pedido no aparecen en el resultado (se indica cuántas se excluyeron). Los precios se actualizan en la API del MINETUR cada ~30 minutos; la respuesta incluye la fecha de esos precios.

Args: municipio_id: ID de municipio MINETUR (lo da buscar_municipio). producto: nombre del carburante en lenguaje natural. Admite alias como "diesel", "glp", "gasolina 95", "gasolina 98", o el nombre exacto de la API (p. ej. "Gasoleo A"). Por defecto gasolina 95 E5. limite: número máximo de gasolineras a devolver, ordenadas por precio ascendente. Por defecto 20 (algunos municipios grandes, como Madrid capital, tienen más de 240 gasolineras).

Returns: Un diccionario con estado: "ok", "sin_gasolineras", "municipio_invalido", "error_conexion" (no se pudo contactar con la API), "error_respuesta" (la API respondió algo que no es JSON), "limite_invalido" (limite no es un entero >= 1), o "producto_no_reconocido" si producto no se pudo resolver. En estado "ok" incluye fecha, producto, total_excluidas, y gasolineras (lista con rotulo, direccion, localidad, horario, precios de todos los productos que vende esa estación como diccionario producto→precio, y coordenadas). En los demás estados incluye mensaje explicando qué pasó y qué hacer.

Inputs: municipio_id (required), limite, producto.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have completely distinct purposes: one searches for municipalities by name to obtain an ID, and the other retrieves fuel prices using that ID. There is no overlap or ambiguity.

    Naming Consistency5/5

    Both tool names follow a consistent verb_noun pattern in Spanish (buscar_municipio, precios_carburantes), which is predictable and clear.

    Tool Count4/5

    With only 2 tools, the server is slightly under the typical range for a focused domain, but it effectively covers the essential workflow of searching municipalities and retrieving prices. It earns its place without being too thin.

    Completeness4/5

    The tools cover the core functionality: municipality lookup and price retrieval. Minor gaps exist, such as lack of geolocation-based search or historical price data, but the set is sufficient for the intended use case.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides access to Korea Petroleum Corporation's Opinet fuel price API for South Korea. Enables querying of current national and regional fuel averages, recent price trends, lowest-price stations, and nearby gas station details through natural language.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for UK fuel prices, enabling queries for cheapest stations, nearby forecourts, and area price summaries using official government open data.
      4
      1
      MIT