Invoice Tools

MCP tools for querying energy invoices and consumption data (Scope 1 & 2)

Query energy invoices — electricity, gas, water, diesel, and other consumption records linked to a facility. Each invoice has quantity, dates, and CO₂e emissions. This covers Scope 1 (stationary combustion) and Scope 2 (purchased energy) data.

Both facility_id and invoice_type are required. Call list_facilities first to discover facility IDs, then query invoices by type.

list_invoices

List energy invoices for a specific facility filtered by type.

Parameters:

Parameter	Type	Required	Default	Description
facility_id	string	Yes	—	UUID of the facility
invoice_type	string	Yes	—	Invoice type (see below)
organization_id	string	No	default org	Organization UUID
status	string	No	—	Status filter: active, deleted
start_date	string	No	—	Filter from this date (YYYY-MM-DD)
end_date	string	No	—	Filter until this date (YYYY-MM-DD)
page	integer	No	1	Page number
size	integer	No	50	Results per page (max 100)

Invoice Types

Value	Scope	Description
electricity	Scope 2	Electricity consumption
natural_gas	Scope 1	Natural gas
diesel	Scope 1	Diesel fuel
water	—	Water consumption
heat	Scope 2	District heating
recharge	Scope 1	Electric vehicle recharging
process	Scope 1	Industrial process fuels

Example response:

{
  "items": [
    {
      "id": "b46d1f0a-...",
      "type": "electricity",
      "status": "active",
      "quantity": 3060.8,
      "co2e": 1347.0,
      "start_date": "2025-06-30T00:00:00",
      "end_date": "2025-07-31T00:00:00",
      "facility_id": "4cc2ac22-...",
      "cups": "ES0022000006089269MY1P"
    }
  ],
  "total": 480,
  "total_pending": 12,
  "total_filtered": 13,
  "page": 1,
  "size": 50
}

Key response fields:

Field	Description
type	Invoice type (matches the invoice_type filter)
quantity	Consumption amount (kWh for electricity, m³ for gas/water, etc.)
co2e	Calculated CO₂e emissions in kg
start_date / end_date	Billing period
cups	CUPS supply point code (Spanish energy market identifier)
total_filtered	The count to paginate against — matches items across every page and size
total / total_pending	Badge counters (active/uploaded and loading respectively) scoped to the same filters, not a pagination total

Example prompts:

"List electricity invoices for our Madrid office"
"Show gas invoices from last quarter"
"What's our water consumption at facility abc-123?"
"Show diesel invoices for 2024"
"Which invoices have the highest CO₂ emissions?"

create_invoice

Create a new energy invoice for a facility. The invoice is allocated 100% to the specified facility.

Parameters:

Parameter	Type	Required	Description
invoice_type	string	Yes	Invoice type: heat, electricity, water, recharge, or process
base_quantity	number	Yes	Consumption quantity (must be >= 0)
unit_id	string	Yes	UUID of the measurement unit (e.g. kWh, m³)
facility_id	string	Yes	UUID of the facility
start_date	string	Yes	Invoice period start date (YYYY-MM-DD)
end_date	string	Yes	Invoice period end date (YYYY-MM-DD)
supplier_id	string	No	UUID of the energy supplier
stationary_fuel_id	string	No	UUID of the stationary fuel type (for heat/process)
refrigerant_fuel_id	string	No	UUID of the refrigerant fuel type
custom_emission_factor_id	string	No	UUID of a custom emission factor
invoice_number	string	No	External invoice number or identifier
cups	string	No	CUPS code (electricity supply point, Spain)
base_total_spend	number	No	Total monetary amount
currency_unit_id	string	No	UUID of the currency unit
self_consumption	boolean	No	Self-consumed electricity (only for electricity type)
organization_id	string	No	Organization UUID (uses default if not set)

Example prompts:

"Create an electricity invoice for 3000 kWh at our Madrid facility for January 2025"
"Add a gas invoice for facility abc-123 with 500 m³ consumption"

update_invoice

Update an existing invoice. Only provided fields are changed (partial update).

Parameters:

Parameter	Type	Required	Description
invoice_id	string	Yes	UUID of the invoice to update
facility_id	string	No	New facility UUID
supplier_id	string	No	New supplier UUID
status	string	No	New status: uploaded, loading, active, inactive, review, or error
invoice_number	string	No	New external invoice number
cups	string	No	New CUPS code
enabled	boolean	No	Whether the invoice is enabled for calculations
self_consumption	boolean	No	Whether this is self-consumed electricity
organization_id	string	No	Organization UUID (uses default if not set)

Example prompts:

"Set invoice b46d1f0a-... to inactive"
"Disable invoice calculations for invoice abc-123"
"Change the supplier for our latest electricity invoice"

recalculate_invoices

Enqueue recalculation of one or more activity categories for a set of invoices. Use this to force emissions to be rebuilt after a data fix (e.g. a corrected emission factor) without waiting for the invoice to be re-uploaded.

All invoice_ids must belong to the same organization and share a single supported invoice type (heat or electricity); ids outside the caller’s organization are silently dropped. Recalculation runs asynchronously — the response returns processing_job_ids (one per activity_category); poll list_processing_jobs for progress and per-record failures.

This endpoint is scoped to one organization per call. To fix the same issue across multiple organizations, call recalculate_invoices once per organization.

Parameters:

Parameter	Type	Required	Description
invoice_ids	array of strings	Yes	UUIDs of the invoices to recalculate (max 5000)
activity_categories	array of strings	Yes	Categories to recalculate (see below)
organization_id	string	No	Organization UUID (uses default if not set)

Activity Categories

Value	Description
stationary	Direct stationary combustion (Scope 1)
stationary_generation	Upstream (WTT) stationary combustion
electricity	Market-based electricity (Scope 2)
electricity_location_based	Location-based electricity (Scope 2)
electricity_generation	Upstream electricity generation
electricity_transmission_and_distribution	Electricity T&D losses
energy	Combined energy category
recharge	Refrigerant gas recharge
water	Water consumption

Example response:

{
  "invoice_ids": ["b46d1f0a-...", "c57e2a1b-..."],
  "count": 2,
  "processing_job_ids": ["9f1e4c3d-..."]
}

Example prompts:

"Recalculate energy emissions for these 7 invoices"
"Re-run the electricity calculation for invoice b46d1f0a-..."

Workflow

1. Find facilities — list_facilities to discover facility IDs
2. List invoices by type — list_invoices with facility_id and invoice_type
3. Create invoices — create_invoice to add new consumption records
4. Update invoices — update_invoice to change status, supplier, or toggle calculations
5. Fix and recalculate — recalculate_invoices to rebuild emissions after a data correction, then list_processing_jobs to confirm it finished
6. View emissions — get_greenhouse_gas_emissions with category=electricity (or stationary, etc.) for aggregated totals

Related

API: List Invoices

REST API equivalent with additional filters

Facilities

Find facility IDs to query invoices

Emissions

Aggregated Scope 1 & 2 emissions

CLI

Manage invoices from the command line