API Reference

REST Client

class fuelog.FuelogClient(token, base_url='https://api.fuelog.app', timeout=30)

Bases: object

Synchronous client for the Fuelog REST API.

Parameters:

• token (str) – Bearer token used for all requests.

• base_url (str) – Override the default API base URL (useful for testing).

• timeout (int) – HTTP timeout in seconds (default: 30).

Example:

client = FuelogClient(token="sk-...")
vehicle_id = client.create_vehicle(
    CreateVehicleRequest(
        name="My Car",
        make="Toyota",
        model="Corolla",
        year="2022",
        fuel_type=FuelType.PETROL,
    )
)

list_logs(limit=100)

Retrieve fuel logs for the authenticated user, newest first.

Parameters:

limit (int) – Maximum number of entries to return (default 100).

Returns:

List of FuelLog objects.

Return type:

list[FuelLog]

create_log(request)

Create a new fuel log entry.

Parameters:

request (CreateFuelLogRequest) – A CreateFuelLogRequest with the required fields.

Returns:

The newly created log’s ID string.

Raises:

FuelogForbiddenError – If the token lacks the write:logs scope.

Return type:

str

update_log(log_id, request)

Update an existing fuel log entry.

Parameters:

• log_id (str) – ID of the log to update.

• request (UpdateFuelLogRequest) – Fields to update wrapped in UpdateFuelLogRequest.

Returns:

True on success.

Raises:

• FuelogNotFoundError – If no log with log_id exists.

• FuelogForbiddenError – If the token lacks the write:logs scope.

Return type:

bool

delete_log(log_id)

Delete a fuel log entry.

Parameters:

log_id (str) – ID of the log to delete.

Returns:

True on success.

Raises:

• FuelogNotFoundError – If no log with log_id exists.

• FuelogForbiddenError – If the token lacks the write:logs scope.

Return type:

bool

list_vehicles(include_archived=False)

Retrieve the user’s vehicle profiles.

Parameters:

include_archived (bool) – When True, archived vehicles are included.

Returns:

List of Vehicle objects.

Return type:

list[Vehicle]

create_vehicle(request)

Register a new vehicle.

Parameters:

request (CreateVehicleRequest) – A CreateVehicleRequest with the required fields.

Returns:

The newly created vehicle’s ID string.

Raises:

FuelogForbiddenError – If the token lacks the write:vehicles scope.

Return type:

str

update_vehicle(vehicle_id, request)

Update an existing vehicle profile.

Parameters:

• vehicle_id (str) – ID of the vehicle to update.

• request (UpdateVehicleRequest) – Fields to update wrapped in UpdateVehicleRequest.

Returns:

True on success.

Raises:

• FuelogNotFoundError – If no vehicle with vehicle_id exists.

• FuelogForbiddenError – If the token lacks the write:vehicles scope.

Return type:

bool

delete_vehicle(vehicle_id)

Delete a vehicle profile.

Parameters:

vehicle_id (str) – ID of the vehicle to delete.

Returns:

True on success.

Raises:

• FuelogNotFoundError – If no vehicle with vehicle_id exists.

• FuelogForbiddenError – If the token lacks the write:vehicles scope.

Return type:

bool

get_analytics(vehicle_id=None, start_date=None, end_date=None)

Retrieve aggregated fuel efficiency and cost statistics.

Parameters:

• vehicle_id (str | None) – Optional vehicle ID to scope the analytics.

• start_date (str | None) – Optional ISO 8601 start date filter.

• end_date (str | None) – Optional ISO 8601 end date filter.

Returns:

An AnalyticsStats object.

Return type:

AnalyticsStats

MCP Client

class fuelog.FuelogMCPClient(token, base_url='https://api.fuelog.app', timeout=30)

Bases: object

Client for the Fuelog MCP server at /api/mcp.

Parameters:

• token (str) – Bearer token used for all requests.

• base_url (str) – Override the default API base URL (useful for testing).

• timeout (int) – HTTP timeout in seconds (default: 30).

list_logs(limit=100, vehicle_id=None, start_date=None, end_date=None, brand=None)

Invoke the list_logs MCP tool.

Parameters:

• limit (int) – Maximum entries to return (default 100).

• vehicle_id (str | None) – Optional vehicle filter.

• start_date (str | None) – Optional ISO 8601 start filter.

• end_date (str | None) – Optional ISO 8601 end filter.

• brand (str | None) – Optional brand/station name filter.

Returns:

MCPToolResult

Return type:

MCPToolResult

log_fuel(brand, cost, distance_km, fuel_amount_liters, currency=None, original_cost=None, exchange_rate=None, vehicle_id=None, timestamp=None, latitude=None, longitude=None)

Invoke the log_fuel MCP tool.

Requires the write:logs scope.

Returns:

MCPToolResult

Return type:

MCPToolResult

edit_fuel_log(log_id, brand=None, cost=None, distance_km=None, fuel_amount_liters=None, currency=None, original_cost=None, exchange_rate=None, vehicle_id=None)

Invoke the edit_fuel_log MCP tool.

Requires the write:logs scope.

Parameters:

log_id (str) – ID of the log entry to update.

Returns:

MCPToolResult

Return type:

MCPToolResult

delete_fuel_log(log_id)

Invoke the delete_fuel_log MCP tool.

Requires the write:logs scope. The confirm: true parameter is added automatically.

Parameters:

log_id (str) – ID of the log entry to permanently delete.

Returns:

MCPToolResult

Return type:

MCPToolResult

list_vehicles(include_archived=False)

Invoke the list_vehicles MCP tool.

Returns:

MCPToolResult

Return type:

MCPToolResult

add_vehicle(name, make, model, year, fuel_type, is_default=None)

Invoke the add_vehicle MCP tool.

Requires the write:vehicles scope.

Returns:

MCPToolResult

Return type:

MCPToolResult

update_vehicle(vehicle_id, name=None, make=None, model=None, year=None, fuel_type=None, is_default=None, is_archived=None)

Invoke the update_vehicle MCP tool.

Requires the write:vehicles scope.

Returns:

MCPToolResult

Return type:

MCPToolResult

get_analytics(vehicle_id=None, start_date=None, end_date=None)

Invoke the get_analytics MCP tool.

Returns:

MCPToolResult

Return type:

MCPToolResult

compare_vehicles(vehicle_ids=None, start_date=None, end_date=None)

Invoke the compare_vehicles MCP tool.

Returns:

MCPToolResult

Return type:

MCPToolResult

read_resource(uri)

Read an MCP resource by its fuelog:// URI.

Available resources: - fuelog://logs - fuelog://logs/{id} - fuelog://vehicles - fuelog://vehicles/{id} - fuelog://analytics/summary - fuelog://analytics/monthly - fuelog://analytics/vehicles - fuelog://profile

Returns:

The parsed resource contents (dict or list).

Return type:

Any

get_all_logs_resource()

Read the fuelog://logs resource (up to 200 entries).

get_log_resource(log_id)

Read a specific log resource by ID.

get_vehicles_resource()

Read the fuelog://vehicles resource.

get_vehicle_resource(vehicle_id)

Read a specific vehicle resource by ID.

get_analytics_summary_resource()

Read the fuelog://analytics/summary resource.

get_analytics_monthly_resource()

Read the fuelog://analytics/monthly resource.

get_analytics_vehicles_resource()

Read the fuelog://analytics/vehicles resource.

get_profile_resource()

Read the fuelog://profile resource.

monthly_report(month, vehicle_id=None)

Get the monthly_report prompt populated with data.

Parameters:

• month (str) – Target month in YYYY-MM format.

• vehicle_id (str | None) – Optional vehicle scope.

Returns:

MCPPromptResult

Return type:

MCPPromptResult

trend_analysis(start_date, end_date, metric=None, vehicle_id=None)

Get the trend_analysis prompt populated with data.

Parameters:

• start_date (str) – ISO 8601 start date.

• end_date (str) – ISO 8601 end date.

• metric (TrendMetric | str | None) – One of kml, mpg, l100km, or cost.

• vehicle_id (str | None) – Optional vehicle scope.

Returns:

MCPPromptResult

Return type:

MCPPromptResult

cost_optimization(period=None)

Get the cost_optimization prompt populated with data.

Parameters:

period (CostOptimizationPeriod | str | None) – One of last_month, last_quarter (default), or last_year.

Returns:

MCPPromptResult

Return type:

MCPPromptResult

Models

Fuel Logs

class fuelog.FuelLog(id, brand=None, cost=None, distance_km=None, fuel_amount_liters=None, currency=None, original_cost=None, exchange_rate=None, vehicle_id=None, latitude=None, longitude=None, timestamp=None)

Bases: object

A single fuel log entry returned by the API.

All fields other than id are optional because the GET endpoint returns whatever the server stored at creation time.

id: str

brand: str | None = None

cost: float | None = None

distance_km: float | None = None

fuel_amount_liters: float | None = None

currency: str | None = None

original_cost: float | None = None

exchange_rate: float | None = None

vehicle_id: str | None = None

latitude: float | None = None

longitude: float | None = None

timestamp: str | None = None

classmethod from_dict(data)

to_dict()

Serialise to a dict suitable for the POST/PUT request body.

class fuelog.CreateFuelLogRequest(brand, cost, distance_km, fuel_amount_liters, currency=None, original_cost=None, exchange_rate=None, vehicle_id=None, latitude=None, longitude=None, timestamp=None)

Bases: object

Parameters required to create a new fuel log entry.

brand: str

cost: float

distance_km: float

fuel_amount_liters: float

currency: str | None = None

original_cost: float | None = None

exchange_rate: float | None = None

vehicle_id: str | None = None

latitude: float | None = None

longitude: float | None = None

timestamp: str | None = None

to_dict()

class fuelog.UpdateFuelLogRequest(brand=None, cost=None, distance_km=None, fuel_amount_liters=None, currency=None, original_cost=None, exchange_rate=None, vehicle_id=None, latitude=None, longitude=None, timestamp=None)

Bases: object

Parameters accepted when updating an existing fuel log entry.

All fields are optional — only non-None fields are sent to the API.

brand: str | None = None

cost: float | None = None

distance_km: float | None = None

fuel_amount_liters: float | None = None

currency: str | None = None

original_cost: float | None = None

exchange_rate: float | None = None

vehicle_id: str | None = None

latitude: float | None = None

longitude: float | None = None

timestamp: str | None = None

to_dict()

Vehicles

class fuelog.Vehicle(id, name=None, make=None, model=None, year=None, fuel_type=None, is_default=None, is_archived=None)

Bases: object

A vehicle profile returned by the API.

id: str

name: str | None = None

make: str | None = None

model: str | None = None

year: str | None = None

fuel_type: str | None = None

is_default: bool | None = None

is_archived: bool | None = None

classmethod from_dict(data)

class fuelog.CreateVehicleRequest(name, make, model, year, fuel_type, is_default=None)

Bases: object

Parameters required to register a new vehicle.

name: str

make: str

model: str

year: str

fuel_type: FuelType

is_default: bool | None = None

to_dict()

class fuelog.UpdateVehicleRequest(name=None, make=None, model=None, year=None, fuel_type=None, is_default=None, is_archived=None)

Bases: object

Parameters accepted when updating a vehicle. All fields are optional.

name: str | None = None

make: str | None = None

model: str | None = None

year: str | None = None

fuel_type: FuelType | str | None = None

is_default: bool | None = None

is_archived: bool | None = None

to_dict()

Analytics

class fuelog.AnalyticsStats(log_count=None, total_spent=None, home_currency=None, total_fuel_liters=None, total_distance_km=None, efficiency=None, avg_cost_per_liter=None, avg_cost_per_km=None, extra=<factory>)

Bases: object

Aggregated analytics stats returned by get_analytics().

log_count: int | None = None

total_spent: float | None = None

home_currency: str | None = None

total_fuel_liters: float | None = None

total_distance_km: float | None = None

efficiency: float | None = None

avg_cost_per_liter: float | None = None

avg_cost_per_km: float | None = None

extra: dict[str, Any]

classmethod from_dict(data)

MCP Results

class fuelog.MCPToolResult(content, is_error=False)

Bases: object

Result returned by an MCP tool invocation.

content: list[dict[str, Any]]

is_error: bool = False

classmethod from_dict(data)

property text: str

concatenate all text-type content blocks.

Type:

Convenience

class fuelog.MCPPromptResult(description, messages)

Bases: object

Result returned by an MCP prompt/get invocation.

description: str | None

messages: list[MCPPromptMessage]

classmethod from_dict(data)

class fuelog.MCPPromptMessage(role, content)

Bases: object

A single message in an MCP prompt response.

role: str

content: dict[str, Any]

classmethod from_dict(data)

Enumerations

class fuelog.FuelType(*values)

Bases: str, Enum

Fuel type accepted by the Fuelog API.

PETROL = 'Petrol'

DIESEL = 'Diesel'

HYBRID = 'Hybrid'

ELECTRIC = 'Electric'

class fuelog.TrendMetric(*values)

Bases: str, Enum

Metric selector for the trend_analysis MCP prompt.

KML = 'kml'

MPG = 'mpg'

L100KM = 'l100km'

COST = 'cost'

class fuelog.CostOptimizationPeriod(*values)

Bases: str, Enum

Time window for the cost_optimization MCP prompt.

LAST_MONTH = 'last_month'

LAST_QUARTER = 'last_quarter'

LAST_YEAR = 'last_year'