Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gasolineras-mcp encuentra la gasolina más barata en Barcelona"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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:
Tener el programa en tu máquina.
Decirle al cliente qué comando ejecutar para arrancarlo.
Related MCP server: Renfe MCP Server
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 | shEn 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-mcpEl -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-mcpGemini CLI (Google):
gemini mcp add -s user gasolineras uvx gasolineras-mcpopencode: 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.
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.
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:
Lista los servidores registrados: claude mcp list, codex mcp list o
gemini mcp list, según tu cliente. Debe salir gasolineras conectado.
Abre una sesión nueva (las abiertas no cargan MCPs nuevos).
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).
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| nombre | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description fully discloses behavior: token-based search (not exact match), return of province even if not requested, and empty list on no match. It also mentions specific examples to illustrate fuzzy matching.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with no extraneous information. It is structured with clear sections: purpose, usage context, parameter description, and return format. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input (one required parameter) and presence of an output schema, the description covers all necessary aspects: why the tool is needed, how search works, what the return includes, and edge cases (duplicates, empty list).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% coverage for 'nombre', but the description defines it as 'nombre o parte del nombre del municipio a buscar' and explains token-based search, adding substantial meaning beyond the schema's default title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches Spanish municipalities by name to obtain their ID, explicitly linking it to the sibling tool precios_carburantes. It distinguishes itself by detailing the token-based search and handling of duplicate names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool (to get a municipality ID for precios_carburantes), provides examples of token-based matching, notes that province is always returned due to duplicates, and mentions the return format, giving clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limite | No | ||
| producto | No | gasolina 95 e5 | |
| municipio_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses ordering (ascending price), exclusion of non-selling stations, update frequency (~30 min), and all possible return states (ok, sin_gasolineras, etc.) with explanations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args and Returns sections, and purpose is front-loaded. It could be slightly more concise by reducing redundancy in ordering and exclusion details, but overall good.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description details the return structure (states, fields like fecha, producto, gasolineras with subfields) and all error conditions. It fully covers what the tool returns and how to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description adds extensive detail for each parameter: municipio_id references buscar_municipio, producto lists aliases and default, limite explains max number and default. This adds significant meaning beyond schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns prices of a fuel in gas stations of a municipality, specifying the verb (precios de), resource (carburante), and scope (gasolineras de un municipio). It distinguishes from the sibling tool buscar_municipio by referencing it for the municipality ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains using the ID from buscar_municipio, defaults, ordering, and exclusion. It does not explicitly state when not to use the tool or list alternatives, but the usage context is well-covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0buscar_municipioprecios_carburantesScored across 2 tools
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.
Both tool names follow a consistent verb_noun pattern in Spanish (buscar_municipio, precios_carburantes), which is predictable and clear.
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.
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.
Real-time fuel prices, alerts, and cheapest gas stations across 38+ countries.
Gas and fuel prices by station and area, as structured data via a hosted MCP server.
Tankerkoenig MCP — German real-time fuel prices (Benzinpreise) for all
Vanlife & RV travel data. Fuel, weather, currency, events, news. https://openvan.camp/en/developers
