IoTaWatt MCP Server

A Model Context Protocol server for the IoTaWatt open-source energy monitor. It lets an MCP client such as Claude Code or Claude Desktop read live power, query the on-device history log, inspect the device configuration, and look at the shape of the current on a circuit.

All tools are read-only. The server talks to the IoTaWatt's local HTTP API and needs no cloud account.

This project is not affiliated with or endorsed by IoTaWatt, Inc.

Requirements

• Node.js 18 or newer

• An IoTaWatt reachable over HTTP from the machine running the server

Related MCP server: Network Monitor MCP Server

Install

git clone https://github.com/519Green/IotaWattMCP.git
cd IotaWattMCP
npm install

Configure

The device address is given with --host or the IOTAWATT_HOST environment variable. Use an IP address or hostname, for example 192.168.1.50 or iotawatt.local. A full URL such as https://iotawatt.example.net also works if the device sits behind a proxy.

Claude Code

Add to .mcp.json in your project, or to your user configuration:

{
  "mcpServers": {
    "iotawatt": {
      "command": "node",
      "args": ["/path/to/IotaWattMCP/index.js", "--host", "192.168.1.50"]
    }
  }
}

Claude Desktop

Add the same iotawatt block under mcpServers in claude_desktop_config.json.

Password-protected devices

If the IoTaWatt has passwords set, give the server one through the environment:

{
  "mcpServers": {
    "iotawatt": {
      "command": "node",
      "args": ["/path/to/IotaWattMCP/index.js", "--host", "192.168.1.50"],
      "env": { "IOTAWATT_PASSWORD": "your-admin-password" }
    }
  }
}

• The account defaults to admin. Set IOTAWATT_USER to user to use the device's restricted account instead. That account can do everything except sample_waveform.

• --user and --password flags also work, but command-line arguments are visible to other processes on the machine. Prefer the environment.

• The device uses HTTP Digest authentication, so the password is not sent in the clear. The data itself still travels over plain HTTP.

Tools

Query notes

query passes its arguments to the IoTaWatt query API.

• select is a list of series. Put time.local.iso first to get timestamps.

• Add a unit suffix to a channel name to change what is returned: .watts, .wh, .amps, .va, .var, .varh or .pf for power channels, .volts or .hz for voltage. Add .d2 for two decimal places.

• begin and end accept relative times (d for today at midnight, s for now, d-7d, s-3600s) or absolute times such as 2026-02-17T06:00. Leave the seconds off absolute times.

• group is the aggregation interval. Seconds must be a multiple of 5 (5s, 10s, 30s); then 1m, 1h, 1d and so on, or all for one row.

• The device returns at most 1,000 rows unless you pass limit. When a result is cut short, the tool adds a note saying where the data stops.

• Results come back one row per line. format: "csv" is the more compact of the two.

Waveform notes

sample_waveform describes the shape of the current, which says what kind of load is running:

• A heater or kettle draws a clean sine wave in step with the voltage: low distortion, crest factor near 1.4, lag near zero.

• A motor or compressor lags the voltage.

• Electronics draw a narrow, peaky current: high crest factor and a large 3rd harmonic.

The numbers are raw ADC counts, not amps, and the capture is everything on that CT at that instant, not a single appliance. Compare a capture with the appliance on against one with it off.

Example prompts

Once the server is connected, ask in plain language. The assistant picks the tools. It helps to tell it what you already know, for example which appliances are on which circuit.

Getting oriented

• "What channels does my IoTaWatt have, and what does each one measure?"

• "Is the device healthy? Check the firmware version, uptime, Wi-Fi signal and how far back the logs go."

• "What is the house drawing right now, by circuit?"

Energy use

• "How many kWh did each circuit use yesterday? Rank them."

• "Show hourly energy for the water heater over the last 7 days. When does it run most?"

• "Compare this week with last week, circuit by circuit."

• "What is my always-on load? Find the quietest hour of the past week and break it down by circuit."

Finding appliances

• "Did the dryer run today? Look for a 240 V load of about 5 kW that cycles on and off."

• "Find the fridge's defrost cycles on the kitchen circuit over the last 3 days. How often do they happen and how long do they last?"

• "Something drew about 1.5 kW for a few minutes around 3 pm. Which circuit was it on, and does the power factor look like a heater or a motor?"

• "How many times did the well pump run today, and how long was each run?"

• "Watch all circuits for the next 60 seconds. I am going to switch the space heater on, then off. Tell me which circuit it is on and how much it draws."

• "Sample the waveform on the office circuit. Is that load mostly electronics, motors or heating?"

Checking the installation

• "Compare each subpanel's total against the mains that feed it. Do any CTs look reversed, mislabelled or on the wrong leg?"

• "Read my output formulas. Does anything get counted twice or left out?"

Tips

• For short events, ask for fine resolution over a short window, such as 5 second data for one hour. The device keeps 5 second data for about a year and 1 minute data for longer.

• A 240 V appliance shows up on two CTs at once, one per leg. A 120 V appliance shows up on one.

• Ask for a summary, not the raw rows. Long, fine-grained queries return a lot of data.

Things to know

• get_config returns the whole config file. If you have uploaders configured (InfluxDB, Emoncms, PVoutput), that file can contain their URLs and credentials, and they will be passed to the MCP client.

• Queries pause sampling. The IoTaWatt documentation notes that the device does not sample power while it is answering a query. Prefer a few well-scoped queries over many large ones. watch is light by comparison: one small request a second.

• Channel names are cached. Call discover after changing inputs or outputs on the device.

• Password support is tested against a mock, built from the IoTaWatt firmware source, not against a real password-protected unit. Please open an issue if it fails on yours.

Development

npm test

The tests start the server over stdio against a small mock IoTaWatt in test/mock-iotawatt.js, so they need no device.

License

ISC. See LICENSE.