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.

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.