portugal-fuel-ev-mcp
Find cheapest fuel stations and public EV chargers in Portugal using official open data.
Search fuel prices by fuel type, district, municipality, coordinates/radius, brand, and limit, returning cheapest-first stations with prices, address, coordinates, distance, and last update.
Get full details for a fuel station: all fuels/prices, opening hours, services, and payment methods.
List DGEG fuel types and accepted districts when you need valid names.
Search EV charging sites near a point by radius, minimum power, connector, availability, and limit, with live status, power, connectors, prices, and data freshness.
Get full EV charger details by site ID, point ID, or EVSE ID, including status, pricing, operator contact, hours, and authentication methods.
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., "@portugal-fuel-ev-mcp cheapest diesel in Sintra for 5 stations"
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.
portugal-fuel-ev-mcp
Deprecated — use portugal-mcp instead. This server now lives on as the energia feature of portugal-mcp, together with IPMA weather, INE, Banco de Portugal, Parliament, public contracts and more. Install with uvx portugal-mcp (add PORTUGAL_MCP_FEATURES=energia to load only this part). Tool names: all tool names are unchanged. This repository gets no further updates.
MCP server that answers "where is the cheapest place to fill up / charge near me in Portugal?", for combustion cars and electric cars, so Claude (or any MCP client) can look it up from official open data.
Read-only, no keys, no account. Fuel prices come from DGEG's official price site; EV chargers, live status and prices come from the MOBI.E network feeds on Portugal's National Access Point. Not affiliated with DGEG, MOBI.E or IMT.
Tools
fuel_prices
Cheapest stations for one fuel type, cheapest first.
Parameters:
fuel_type— a DGEG fuel name or id ("Gasóleo simples","Gasolina simples 95","Gasolina 98","GPL Auto"...) or plain words:"diesel","petrol","95","98","lpg","cng"district— e.g."Lisboa","Porto","Faro"(case- and accent-insensitive)municipality— e.g."Sintra","Évora"(overridesdistrict)lat/lon+radius_km— search around a point (default radius 10 km)brand— only one brand, e.g."Galp","Prio"limit— how many stations (default 10, max 50)
With no area it searches all of Portugal. Each station has: price (EUR per litre, or per kg/m³ for gas), brand, name, address, municipality, coordinates, distance (when searching around a point) and the station's last price update. The result also gives how many stations matched and the min/median/max price.
fuel_station_detail
One station: every fuel it sells with price and last update, opening hours, services and payment methods.
fuel_types
The DGEG fuel types (id, name, unit) and the districts. Only needed when unsure which fuel name to use.
ev_chargers
Public charging sites near a point, nearest first, with live status and published prices.
Parameters:
lat/lon— where to searchradius_km— default 5, max 100min_power_kw— e.g.50for fast DCconnector—"CCS","Type 2","CHAdeMO","CEE", or"DC"/"AC"available_only— only points that are free right nowlimit— sites to return (default 10, max 50)
Each site has: operator, address, distance, opening hours and its matching points. Each point has: live status (available, in use, out of order...), maximum power, connectors and the price the feed publishes (per_kwh, per_minute, per_session, in EUR). The result also says how fresh the data is.
ev_charger_detail
One charging site by site id, point id or EVSE id: all its points with status, power, connectors and price, plus the operator's contact, opening hours and how you can start a charge (app, RFID card, credit card...).
Related MCP server: @cyanheads/openchargemap-mcp-server
About EV prices
The prices are the rates that the MOBI.E status feed publishes for each charging point: a pricing type (per kWh, per minute of charging, per session, or "other", such as parking time) and an amount. They may not be the whole bill:
The feed does not say which tariff it is (regular, or ad hoc / pay at the charger), nor whether VAT is included. A spot check against MOBI.E's own tariff list found that where a point has an ad hoc tariff the feed usually carries that one; elsewhere it carries the operator's regular tariff.
On the MOBI.E network the operator's tariff is only the charging point's fee. When you pay with a MOBI.E card or app, your provider (CEME) adds its own energy price, plus network access charges, the MOBI.E management fee and taxes.
Every ev_chargers and ev_charger_detail result carries this note (price_note). Use the prices to compare chargers, and check the operator's app or your provider for the final cost.
Install
Quickest (needs uv): no clone needed, it runs straight from PyPI.
claude mcp add portugal-fuel-ev -- uvx portugal-fuel-ev-mcpFor Claude Desktop, use "command": "uvx", "args": ["portugal-fuel-ev-mcp"].
From source:
Requires Python 3.10+.
git clone https://github.com/ThiagoJacobLannes/portugal-fuel-ev-mcp
cd portugal-fuel-ev-mcp
python -m pip install -e .On Windows, if you keep code in a cloud-synced folder (Google Drive, OneDrive), create the virtual environment outside it: sync clients drop desktop.ini files into folders, which can crash packages on startup.
Add to Claude Code
claude mcp add portugal-fuel-ev -- python -m portugal_fuel_ev_mcp.serverAdd to Claude Desktop
Merge claude_desktop_config.snippet.json into your Claude Desktop claude_desktop_config.json, then restart Claude Desktop:
{
"mcpServers": {
"portugal-fuel-ev": {
"command": "python",
"args": ["-m", "portugal_fuel_ev_mcp.server"]
}
}
}First EV call is slow
The MOBI.E feeds are large (about 180 MB for the inventory, 40 MB for the live status) and are not compressed. The first EV call of the day downloads them, which takes one to three minutes depending on the connection and on MOBI.E's server. The server reads them as they stream in (it never holds the whole file in memory) and keeps a compact cache of about 1 MB, so later calls take milliseconds.
The inventory is refreshed at most every 24 hours, and the live status every 10 minutes, only when a tool needs them. Each result's
data_freshnesssays when the data was published and fetched.To download ahead of time (for example if your client times out on long calls), run:
python -m portugal_fuel_ev_mcp.server --refreshThe cache lives in your user cache folder (via
platformdirs). SetPORTUGAL_FUEL_EV_CACHE_DIRto use another folder.If a refresh fails, the server keeps using the last cache and says so in
data_freshness.warnings.
Fuel prices are fetched live from DGEG on each call (cached for 10 minutes).
Data sources and licences
Data | Source | Terms |
Fuel prices, stations, opening hours | DGEG, Preços dos Combustíveis Online (JSON API | DGEG's site says the information is free and can be used freely; reuse must name DGEG as the source, show the date and time of the last price update, and reproduce the information faithfully. The tools return |
EV charging sites, points, connectors, live status and prices | MOBI.E, via Portugal's National Access Point (NAP, IMT): | Listed on the NAP (datasets 148 and 149) as "Livre acesso" (open access), with no separate licence document. Credit "MOBI.E / NAP Portugal" when you reuse the data. |
Prices are posted by station operators and charging operators; they can be wrong or out of date. Check at the pump or in the charger's app.
The DGEG endpoints are the ones used by the Home Assistant integration netsoft-ruidias/ha-custom-component-precoscombustiveis and by GeiserX/Pumperly. The DATEX II parsing follows the notes in CarregaErvilhas/nap-dashboard and mobilidade-dados-pt/carregamento-pt.
How it works
Fuel:
PesquisarPostosreturns every station selling one fuel type in an area, with price ("1,899 €", turned into1.899), coordinates and last update; for a point search the server fetches the whole country (about 1 MB) and filters by distance.GetDadosPostogives one station's details.EV: the two DATEX II feeds are parsed incrementally with Python's built-in
xml.etree.ElementTree.XMLPullParser, one charging site at a time. Status and prices are joined to the inventory by (site id, point id), because some operators reuse bare point ids across sites. Requests sendIf-None-Match, so an unchanged feed is not downloaded again.
If a source changes or is down, tools return {"error": ...} instead of wrong data.
License
MIT
Available Tools
5 toolsev_charger_detailA
Everything about one MOBI.E charging site: all its points with live status, power, connectors and price, plus operator contact, opening hours and accepted authentication (app, RFID card, credit card...).
Use after ev_chargers. Accepts a site_id (e.g. "EZC-AMD-00051"), a point_id (e.g. "AMD-00051-1") or an EVSE id (e.g. "PTEZCEAMD00051*1").
Inputs: site_or_point_id (required). Returns: object
ev_chargersA
Public EV charging sites near a point in Portugal (MOBI.E network), nearest first, with live status and the price the network publishes for each charging point.
Use for "where can I charge near X?", "fast chargers near me", "is there a free CCS charger nearby?". Needs coordinates; if the user gives a place name, use known coordinates for it. Covers mainland Portugal, Azores and Madeira.
Args: lat, lon: Point to search around (WGS84). radius_km: Search radius (default 5, max 100). min_power_kw: Only points that can deliver at least this power, e.g. 50 for fast DC. connector: "CCS" (CCS2), "Type 2", "CHAdeMO", "CEE", or "DC" / "AC". available_only: Only points whose live status is "available" right now. limit: Max sites to return (default 10, max 50).
Each site: operator, address, distance_km, opening hours and its matching points, each
with status (available, in use, out of order...), max power, connectors and price
(per_kwh / per_minute / per_session in EUR, from the feed). IMPORTANT: these are the
charging operator's published fees and may not be the whole bill: see price_note and
tell the user. data_freshness says how old the inventory and live status are.
The first call of the day downloads ~220 MB from MOBI.E and can take 1-3 minutes.
Inputs: lat (required), lon (required), limit, connector, +3 more. Returns: object
fuel_pricesA
Cheapest fuel stations in Portugal for one fuel type, cheapest first (official DGEG prices).
Use for "where is diesel/petrol/LPG cheapest in Lisboa / near me / in Braga?". Give an area as a district, a municipality, or a point (lat + lon, with radius_km); with no area it searches all of Portugal. Names are case- and accent-insensitive ("evora" works).
Args: fuel_type: A DGEG fuel name or id, e.g. "Gasóleo simples" (regular diesel, 2101), "Gasolina simples 95" (regular 95 petrol, 3201), "Gasolina 98", "GPL Auto" (LPG), or plain words: "diesel", "petrol", "95", "98", "lpg", "cng". See fuel_types() for the full list. district: Portuguese district, e.g. "Lisboa", "Porto", "Faro". municipality: Municipality (concelho), e.g. "Sintra", "Vila Nova de Gaia". Overrides district. lat, lon: A point (WGS84). Results get distance_km and are limited to radius_km. radius_km: Search radius around lat/lon (default 10). brand: Only this brand (substring match), e.g. "Galp", "Prio", "Intermarché". limit: How many stations to return (default 10, max 50).
Each station: price_eur (per litre, or per kg/m3 for gas), brand, name, address, municipality, distance_km (with lat/lon), coordinates and last_update (the station's last price update). Also returns how many stations matched and the min/median/max price. Always mention the source (DGEG) and the last_update when quoting prices.
Inputs: fuel_type (required), lat, lon, brand, +4 more. Returns: object
fuel_station_detailA
Full details of one fuel station: every fuel it sells with price and last update, opening hours, services (car wash, shop, tyre air...) and payment methods.
Use after fuel_prices, with a station id from its results.
Inputs: station_id (required). Returns: object
fuel_typesA
List DGEG fuel types (id, name, unit) and the districts accepted by fuel_prices.
Only needed when unsure which fuel name to pass; fuel_prices also understands "diesel", "petrol", "95", "98", "lpg".
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
The set cleanly splits into two domains: fuel stations (fuel_prices, fuel_station_detail, fuel_types) and EV charging (ev_chargers, ev_charger_detail). Search tools and detail tools are explicitly paired, and fuel_types is clearly a lookup helper. No two tools appear to do the same thing.
All names use snake_case and follow a domain_action or domain_resource pattern. Minor inconsistency exists between plural list tools (fuel_prices, ev_chargers) and singular detail tools (fuel_station_detail, ev_charger_detail), and fuel_types is a helper rather than an action. Still predictable and readable.
Five tools is well-scoped for a specialized Portugal fuel/EV charging server. Each tool has a clear role: two search tools, two detail tools, and one reference/lookup tool. Nothing feels redundant or missing from the count perspective.
The surface covers the core lifecycle: find fuel stations, inspect a station, list fuel types, find EV chargers, and inspect a charging site. A minor gap is that EV charger search requires coordinates and lacks the district/municipality convenience offered by fuel_prices. Overall complete enough for the stated purpose.
Maintenance
Related MCP Connectors
EV charging sites, plugs, tariffs, live status and history from European national access points.
Open Charge Map MCP — global EV charging station database (openchargemap.io).
Find EV charging stations, detail, and reliability check-ins via the global Open Charge Map.
Real-time fuel prices, alerts, and cheapest gas stations across 38+ countries.
Related MCP Servers
- AlicenseAqualityBmaintenanceProvides real-time fuel prices at gas stations in Spain using the government's public API. Enables users to find the cheapest fuel in a municipality or list stations sorted by price.2MIT
- AlicenseNot gradedqualityBmaintenanceFind EV charging stations by location and connector, get full station detail, resolve reference IDs, and read community reliability check-ins via MCP.120 npm2Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables users to look up official Brazilian fuel station information from a hosted service, paying per query with prepaid credits, across any MCP-compatible client.MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to query live fuel prices across NSW and Tasmania from the API.NSW Fuel API, finding the cheapest or nearest stations around a suburb, postcode or coordinates, listing all current prices at a given station, searching stations by name, brand or location, and looking up fuel type codes. Reference data is cached for 24 hours to conserve monthly API quota.87 PyPIMIT