Shelly Read-Only MCP

A fail-closed, local-only MCP server for inspecting Shelly devices discovered through Home Assistant. It exposes status and redacted configuration, but no switching, 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, automated tests, Docker configuration, and documentation. The project is independently maintained and is not an official OpenAI, Home Assistant, or Shelly product.

AI-assisted code can contain mistakes. Review changes, run the test suite, and validate 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 in Home 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 as that dedicated user

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

Home Assistant account setup

1. In Home Assistant, create a user such as shelly_inventory.

2. Enable local access only.

3. Leave administrator disabled.

4. Sign in locally as that user.

5. Create a dedicated long-lived access token from the user's Security page.

6. 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, or support 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 the Docker host. This lets the non-root container read the mode-600 secret without 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, or configuration tool.

Discovery behavior

Home Assistant is the source of device names, models, entities, and integration membership. Local IP addresses are obtained from state attributes associated with 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 through Home Assistant rather than direct device access.
• The inventory is refreshed lazily when used and is at most ten minutes old by default.
• 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 Linux capabilities, 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.