mqtt-mcp-server

An MCP server for MQTT that remembers. It subscribes to a broker, stores every message with a timestamp in SQLite, and lets an AI agent ask questions about the past — not just about the next message that happens to arrive.

Why another MQTT MCP server

The existing ones answer "wait for the next message on this topic". That is the wrong question for diagnosing home automation:

• A battery-powered sensor (Shelly H&T) sleeps for hours. Waiting for its next message means waiting for hours.

• A broken device sends nothing at all. Waiting tells you nothing — you need to know when it last spoke.

• "No data" is ambiguous. Was the device silent, or was the collector not listening? Without a record of connection state, both look identical.

This server answers all three.

Related MCP server: SQLite MCP Server

Tools

find_silent and get_gaps belong together

find_silent deliberately warns you when connection gaps exist in the queried period. A topic can look "silent" simply because nobody was listening. The server refuses to let you confuse the two.

Install

git clone https://github.com/Schimmilab/mqtt-mcp-server.git
cd mqtt-mcp-server
python3 -m venv .venv
.venv/bin/pip install -e .

Register with Claude Code:

claude mcp add mqtt --scope user \
  --env MQTT_MCP_HOST=192.168.1.10 \
  -- /ABSOLUTE/PATH/TO/mqtt-mcp-server/.venv/bin/mqtt-mcp-server

A newly registered server is only picked up by a new session — MCP connections are fixed at session start.

Configuration

Writing is off by default — on purpose

publish requires two conditions: write mode enabled and the topic not on the block list. The default block list covers power switches and device restarts.

⚠️ The block list is a guard rail, not a security boundary. Anyone with access to the server can change it. Real enforcement requires a broker-side ACL.

The default exists because of a real incident: a switched socket in front of two servers failed and took the whole home automation down for nine days, costing seven weeks of measurement data. Measuring is safe; switching is not.

Retained messages

On connect, a broker delivers its entire retained backlog at once — potentially tens of thousands of messages with old content but a fresh arrival time. Storing those naively corrupts every history from the first second.

This server stores them, but flags them: aus_startschwall: true. get_last uses them (that is how a sleeping sensor still has a value); get_history can exclude them.

Known limitations

Broker authentication is implemented but untested against a real broker. MQTT_MCP_USERNAME / MQTT_MCP_PASSWORD are passed to username_pw_set(), and unit tests verify they reach the client — but no authenticating broker was available during development. If you use auth, verify it works before relying on it.

Two behaviours are only covered by unit tests, not by integration tests: connection loss (get_gaps) and devices going quiet (find_silent). Both are hard to trigger on demand without a controllable broker. A built-in traffic simulator is the obvious fix and is planned.

History only covers times when the server was running. It is a debugging tool started on demand, not a 24/7 collector. If something breaks while you are away and no session is open, nothing is recorded.

Retention

Runs at startup and hourly: delete older than N days, then — if still over the size cap — delete oldest-first. Every cleanup reports what it removed to stderr, including the oldest remaining timestamp. Silent deletion would quietly destroy the answer to "since when has this device been quiet?".

License

MIT