ams-mcp

Reads a home electricity meter by voice. It is a small MCP server that asks the meter's HAN-port reader, an AmsToMqttBridge device on the home network, what it has seen, and answers in a sentence to read aloud. It is made as a plugin for claude-voice, and works with any MCP client over stdio.

It only reads. It sends nothing but GET, to seven JSON pages the reader shows without a login, and never a page that saves a setting, reboots or upgrades (ADR-AM-001).

The five tools

Every answer has say, in kW, kWh and kr, success, and read_at, the time of the reading. A reading older than about 30 seconds, or one the reader has not had from the meter lately, starts "Not confirmed".

Related MCP server: tibber-mcp-server

Try it without the meter

--simulate answers from pages recorded off a real reader, and says so:

$ ams-mcp ask now --simulate
Simulated: Drawing 1.05 kW from the grid now. The phases carry 2.9, 0.9 and 1.5 A. This meter sends no power factor.
$ ams-mcp ask energy --simulate
Simulated: Today 33.2 kWh, 30.85 kr. This hour 0.32 kWh. This month 605 kWh, 548 kr.

Point it at the reader

The address goes in a file of your own, never in this repository:

# ~/.config/ams-mcp/config.toml
[reader]
address = "192.0.2.10"     # the reader's address on your network
timezone = "Europe/Oslo"   # optional; the computer's own by default

Without it, the server says where the file should be and stops:

$ ams-mcp serve --settings-file /nowhere/config.toml
ams-mcp: No settings file at /nowhere/config.toml; write [reader] address = "..." there, or use --simulate.

ams-mcp serve then serves the tools over stdio. For claude-voice:

[plugins.ams]
command = "uv"
args = ["run", "ams-mcp", "serve"]
cwd = "~/ams-mcp"
tools = ["ams_now", "ams_energy", "ams_price", "ams_capacity", "ams_history"]
timeout = 30

What each of the reader's short keys means, read from the firmware's source, is in docs/pages.md.

The gates

Every one of these runs in continuous integration, and all of them run here:

$ uv run ruff check .
All checks passed!

uv run ruff format --check .   # layout
uv run mypy src                # types
uv run pytest -q               # behaviour
python scripts/mutate.py       # that each rule's own test can fail

CONTRIBUTING.md says what each one is for, and decisions/ records the choices that shaped them, including how a change is made here.

Licence

GPL-3.0-or-later. See LICENSE.