# heating-oil-propane-prices-mcp

Heating oil and propane prices for AI assistants. Ask for this week's price per gallon in your state and get the U.S. Energy Information Administration (EIA) average, the change from last week and a year ago, and what a tank fill costs.

This is a Model Context Protocol (MCP) server. It reads the EIA weekly residential heating oil and propane survey at call time. It needs no API key.

## Tools

| Tool | What it returns |
| --- | --- |
| `get_heating_oil_propane_prices` | This week's EIA average residential heating oil and propane price per gallon (taxes included) for the US, an EIA region or a surveyed state, the change from last week, the last five survey weeks, the price a year ago and the next release date. |
| `get_heating_fuel_price_history` | Weekly prices for a fuel and area between two dates (most series start in 1990), with high, low and average. |
| `estimate_heating_fuel_cost` | Cost of a delivery at this week's state average (or your price), cost per million Btu, and heating oil vs propane per million Btu, optionally against your electricity or natural gas rate. |

Every result has structured JSON, a one-paragraph summary, `as_of`, `source` and `more` (a page on [mcpstamp.com](https://www.mcpstamp.com/servers/?utm_source=mcp&utm_medium=heating-oil-propane-prices-mcp)).

## What it knows that your model does not

- This week's price. EIA publishes new prices every Wednesday from October to March, so a remembered number is stale.
- Which states EIA surveys. Heating oil covers 21 Northeast and Midwest states; propane covers 38. Other states get the covered list, not a made-up number.
- Real year-over-year change from the EIA history file.

## Install

### Hosted (Claude.ai custom connector, ChatGPT developer mode)

Paste this URL. No token, no sign-up. It works now.

```
https://heating-oil-propane-prices-mcp.lipmichal.workers.dev/mcp
```

### Claude Code

```
claude mcp add --transport http heating-fuel-prices https://heating-oil-propane-prices-mcp.lipmichal.workers.dev/mcp
```

### Claude Desktop

Claude Desktop adds remote servers under Settings, Connectors, Add custom connector. Paste the URL above.

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "heating-fuel-prices": { "url": "https://heating-oil-propane-prices-mcp.lipmichal.workers.dev/mcp" }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "heating-fuel-prices": { "type": "http", "url": "https://heating-oil-propane-prices-mcp.lipmichal.workers.dev/mcp" }
  }
}
```

### Local stdio (after npm release)

The npm package is not published yet. After it is, run it locally with Node 20 or newer:

```
claude mcp add heating-fuel-prices -- npx -y heating-oil-propane-prices-mcp
```

## Example prompts

- "What are heating oil prices this week?"
- "How much is propane in Maine right now, and how does it compare with last year?"
- "What will 200 gallons of heating oil cost me in Connecticut?"
- "Is propane or heating oil cheaper per Btu in Pennsylvania?"
- "Show me propane prices in Minnesota over the last year."

## Data sources

Full list with fetch dates in [DATA_SOURCES.md](DATA_SOURCES.md).

- [EIA weekly residential heating oil prices](https://www.eia.gov/dnav/pet/pet_pri_wfr_a_EPD2F_prs_dpgal_w.htm) and [propane prices](https://www.eia.gov/dnav/pet/pet_pri_wfr_a_EPLLPA_prs_dpgal_w.htm), read at call time.
- EIA weekly history pages (LeafHandler) for year-ago and history.
- [EIA heat content](https://www.eia.gov/energyexplained/units-and-calculators/british-thermal-units.php): heating oil 138,500 Btu per gallon, propane 91,452 Btu per gallon.

## Limitations

- State averages from a dealer survey, not a quote. Dealer price, delivery fees, volume and contracts vary.
- From April to September EIA collects one price a month.
- Not every state is surveyed (no heating oil price for Texas, for example).
- The hosted server caches EIA pages for up to an hour.

## More

More MCP servers that answer questions your assistant cannot answer alone are on [mcpstamp.com](https://www.mcpstamp.com/servers/?utm_source=mcp&utm_medium=heating-oil-propane-prices-mcp).

Part of the Zovo MCP collection: https://mcp.zovo.one

Built by [theluckystrike](https://github.com/theluckystrike).

## Development

```
npm install
npm test                              # builds, then runs the fixture tests and an offline stdio test
node scripts/stdio-transcript.mjs     # live stdio round trip, writes .live/stdio-transcript.jsonl
```

## License

MIT