Shelly

npm version npm downloads license github repo

MCP server for controlling Shelly Gen2+ devices over your local network.

Features:

• automatic LAN discovery
• strongly typed tools for status, switches, covers, and raw RPC calls

Requirements

• Node.js 20+
• npm 10+
• Shelly Gen2+ devices reachable on your LAN

Install and run

You can run this server in two common ways.

Option A: standalone clone (recommended while developing)

git clone https://github.com/jdgoeij/shelly-mcp-server.git
cd shelly-mcp-server
npm install
npm run build

MCP client config example:

{
  "mcpServers": {
    "shelly-local": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/absolute/path/to/shelly-mcp-server",
      "env": {
        "SHELLY_DEVICES_FILE": "./devices.local.json",
        "SHELLY_DISCOVERY_CONFIG_FILE": "./discovery.config.json",
        "SHELLY_TIMEOUT_MS": "5000"
      }
    }
  }
}

Option B: run from npm with npx

Now that the package is published, users can run it without cloning:

• latest release:

{
  "mcpServers": {
    "shelly-local": {
      "command": "npx",
      "args": ["-y", "shelly-mcp-server"],
      "cwd": "/absolute/path/to/shelly-config",
      "env": {
        "SHELLY_DEVICES_FILE": "./devices.local.json",
        "SHELLY_DISCOVERY_CONFIG_FILE": "./discovery.config.json",
        "SHELLY_TIMEOUT_MS": "5000"
      }
    }
  }
}

• pinned version (recommended for reproducible setups):

{
  "mcpServers": {
    "shelly-local": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "cwd": "/absolute/path/to/shelly-config",
      "env": {
        "SHELLY_DEVICES_FILE": "./devices.local.json",
        "SHELLY_DISCOVERY_CONFIG_FILE": "./discovery.config.json",
        "SHELLY_TIMEOUT_MS": "5000"
      }
    }
  }
}

Important:

• keep cwd pointed at a persistent folder where config/data files live
• the server reads and writes relative paths from that folder

First-time setup for either option

Create local config files in your chosen cwd folder:

discovery.config.json

{
  "cidr": "192.168.1.0/24",
  "merge": true,
  "timeoutMs": 1500,
  "concurrency": 32,
  "maxHosts": 512,
  "validateTimeoutMs": 5000
}

Then ask your MCP client assistant:

Discover and validate my Shelly devices on 192.168.1.0/24

This creates or updates devices.local.json.

Environment variables

Variable	Default	Description
SHELLY_DEVICES_FILE	./devices.local.json	Path to persisted device inventory
SHELLY_DISCOVERY_CONFIG_FILE	./discovery.config.json	Path to discovery defaults
SHELLY_TIMEOUT_MS	5000	RPC timeout in milliseconds

Available tools

Tool	Description
shelly_list_devices	List configured devices
shelly_get_status	Get full device status
shelly_get_device_info	Get model and firmware info
shelly_switch_set	Turn a relay on or off
shelly_cover_control	Open, close, stop, or set position
shelly_rpc_call	Call any Shelly RPC method
shelly_discover_and_save_devices	Discover devices and save to JSON
shelly_discover_save_and_validate	Discover, save, and validate connectivity
shelly_update_device_credentials	Batch-apply credentials to saved devices

• Run this server only on trusted machines.
• Never commit .env, devices.local.json, or cloud credentials.
• Review MCP client config before sharing screenshots or logs.