# 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):

```bash
# 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):

```bash
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:

```json
{
  "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):

```bash
codex mcp add gasolineras -- uvx gasolineras-mcp
```

**Gemini CLI** (Google):

```bash
gemini mcp add -s user gasolineras uvx gasolineras-mcp
```

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

```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.

```bash
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.