Shelly Read-Only MCP

A fail-closed, local-only MCP server for inspecting Shelly devices discoveredthrough Home Assistant. It exposes status and redacted configuration, but noswitching, control, generic RPC, or configuration tools.

Development disclosure

This project was designed and developed with assistance from OpenAI Codex.Codex was used to help create the implementation, security controls, automatedtests, Docker configuration, and documentation. The project is independentlymaintained and is not an official OpenAI, Home Assistant, or Shelly product.

AI-assisted code can contain mistakes. Review changes, run the test suite, andvalidate security-sensitive behavior before deploying or contributing.

Requirements

Docker Engine with Docker Compose
Home Assistant reachable on the local network
The official Shelly integration must already be installed and running inHome Assistant
Shelly devices must be present in the Home Assistant device registry
A dedicated, non-administrator Home Assistant user with local access only
A separate Home Assistant long-lived access token created while signed in asthat dedicated user

Do not use an owner or administrator token. A Home Assistant token is a bearercredential and is not inherently read-only; the server limits itself to threefixed read commands, but a stolen token retains the permissions of its user.

Home Assistant account setup

In Home Assistant, create a user such as shelly_inventory.
Enable local access only.
Leave administrator disabled.
Sign in locally as that user.
Create a dedicated long-lived access token from the user's Security page.

Store the token in a file outside the repository:

mkdir -p ~/.secrets/shelly-readonly-mcp
chmod 700 ~/.secrets ~/.secrets/shelly-readonly-mcp
nano ~/.secrets/shelly-readonly-mcp/ha_token
chmod 600 ~/.secrets/shelly-readonly-mcp/ha_token

Never paste the token into .env, compose.yaml, Git, logs, screenshots, orsupport requests.

Installation

git clone https://github.com/YOUR-ACCOUNT/shelly-readonly-mcp.git
cd shelly-readonly-mcp
cp .env.example .env
nano .env
docker compose up -d --build

Set APP_UID to the owner of the token file. Find it with id -u on theDocker host. This lets the non-root container read the mode-600 secretwithout weakening its filesystem permissions.

Validate the resolved configuration before starting:

docker compose config

Example .env:

APP_UID=1000
HA_HOST=192.168.1.10
MCP_BIND_IP=192.168.1.20
MCP_PORT=3001
HA_INVENTORY_TTL=600
HA_TOKEN_FILE_HOST=/home/your-user/.secrets/shelly-readonly-mcp/ha_token

The MCP endpoint is then:

http://MCP_BIND_IP:3001/mcp

MCP tools

shelly_list_devices
shelly_refresh_inventory
shelly_get_summary
shelly_get_snapshot

There is deliberately no generic RPC, service-call, switch, light, cover, orconfiguration tool.

Discovery behavior

Home Assistant is the source of device names, models, entities, and integrationmembership. Local IP addresses are obtained from state attributes associatedwith the same Home Assistant device. Only private IPv4 targets are accepted.

Gen1 devices use exact query-free GET /shelly, /status, and /settings.
Gen2/Gen3/Gen4 devices use a small allowlist of read-only RPC methods.
Shelly BLU devices have no directly reachable IP and remain available throughHome Assistant rather than direct device access.
The inventory is refreshed lazily when used and is at most ten minutes old bydefault.
The last valid inventory is stored in a Docker volume and survives restarts.
A failed or empty refresh never overwrites the last valid inventory.

Network security

Bind the MCP port to a specific LAN address and restrict it to trusted clients.Example for a Docker host using DOCKER-USER (replace the addresses):

sudo iptables -I DOCKER-USER 1 -p tcp -s 192.168.1.50 --dport 3001 -j ACCEPT
sudo iptables -I DOCKER-USER 2 -p tcp --dport 3001 -j DROP
sudo netfilter-persistent save

Do not expose the MCP endpoint or Home Assistant token to the public internet.

Security model

Deny by default; permit only exact allowlisted read operations.
No arbitrary host, path, query string, RPC method, or Home Assistant command.
Private IPv4 destinations only.
Response size and timeout limits.
Recursive redaction of passwords, tokens, private keys, and URL credentials.
Home Assistant token mounted as a Docker secret, never built into the image.
Persistent cache contains device metadata and local IPs, but no token.
Container runs as a non-root user with a read-only root filesystem, no Linuxcapabilities, and no-new-privileges.

See SECURITY.md for reporting and limitations.

Tests

python -m unittest discover -s tests -v

License

Distributed under the MIT License.

Shelly Read-Only MCP