Skip to main content
Glama
the-mace

Smart Oil Gauge MCP

by the-mace
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Smart Oil Gauge MCP

A small MCP server that reads your Smart Oil Gauge (Connected Consumer Fuel) heating-oil tank data on demand. You don't need Home Assistant.

Smart Oil Gauge has no free owner API. This server logs in to app.smartoilgauge.com with your normal account and calls the same JSON endpoints the web app uses. Each tool call fetches live data, and nothing is stored on disk. It is unofficial and not affiliated with Smart Oil Gauge or Connected Consumer Fuel, so it can break if they change their site.

License: MIT (see LICENSE).

Tools

Tool

Returns

get_tank_status(tank_name=None)

Gallons, percent full, capacity, gallons to fill, usage (gal/day), days until low / one-eighth / empty, battery, sensor status, last reading time

get_usage_history(tank_name=None, include_daily_levels=False)

Gallons used and average gal/day for today, 7, 30 and 365 days, tank temperature (°F), last delivery date and size; optionally the level for each day of the past year

"Days to" estimates use the same rules as the web app: they are null when usage is zero or the sensor hasn't reported for more than 96 hours.

Related MCP server: shelly-api-mcp

Install

Python 3.11 or newer.

git clone https://github.com/the-mace/smart-oil-gauge-mcp.git
cd smart-oil-gauge-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Credentials

Use the email and password you sign in to app.smartoilgauge.com with. Set them in the environment, or put them in a .env file in this repo's folder (git ignores it) or in ~/.env. They are looked up in that order:

SMARTOILGAUGE_USERNAME=you@example.com
SMARTOILGAUGE_PASSWORD=your-password

Check that it works (prints both tools' output for your tanks):

.venv/bin/python src/smart_oil_gauge_mcp.py --check

Add to an MCP client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json). Merge this into any existing mcpServers:

{
  "mcpServers": {
    "smart-oil-gauge": {
      "command": "/path/to/smart-oil-gauge-mcp/.venv/bin/python",
      "args": ["/path/to/smart-oil-gauge-mcp/src/smart_oil_gauge_mcp.py"]
    }
  }
}

Claude Code:

claude mcp add smart-oil-gauge -s user -- \
  /path/to/smart-oil-gauge-mcp/.venv/bin/python /path/to/smart-oil-gauge-mcp/src/smart_oil_gauge_mcp.py

If you don't use ~/.env, pass the two variables in the client's env block instead.

Development

.venv/bin/python -m pytest

Tests use synthetic responses in tests/fixtures/ and never touch the real site. Dependabot opens weekly PRs for Python packages and GitHub Actions. Once CI passes, patch and minor bumps merge automatically (patch only for 0.x packages); majors wait for review.

Credits

The login flow, endpoints and estimate rules come from these Home Assistant integrations (both MIT):

Also see the smart-oil-gauge GitHub topic.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • claude-spend

    mpalermiti
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides tools for Claude to query local Claude Code token usage and cost data, enabling spend analysis and insights through natural language.
    5 npm
    1
    MIT

  • shelly-api-mcp

    adambenhassen
    F
    license
    Not graded
    quality
    C
    maintenance
    Provides read-only access to Shelly Cloud energy data, including live power, lifetime energy, and historical consumption with cost, enabling AI agents to monitor electricity usage without device control.
    1
    -

  • claude-usage

    AlbeeDev
    A
    license
    Not graded
    quality
    A
    maintenance
    Provides Claude plan usage data (session and weekly percentages) as an MCP tool by reading through a logged-in browser, enabling Claude to check its own remaining usage.
    MIT