Plugwise MCP Server

A TypeScript-based Model Context Protocol (MCP) server for Plugwise smart home integration with automatic network discovery.

✨ Key Features

🤖 AI Agent Mode: Natural language control via built-in AI agent
📡 JSON-RPC Support: Programmatic API for scripting and automation
🔍 Automatic Network Scanning: Discovers all Plugwise hubs on your network
🔐 Credential Management: Stores hub passwords securely from .env file
🔌 Device Control: Control thermostats, switches, and smart plugs
🌡️ Temperature Management: Set temperatures, presets, and schedules
📊 Energy Monitoring: Read power consumption and sensor data
🏠 Multi-Hub Support: Manage multiple gateways simultaneously
🔄 Real-time Updates: Get current device states and measurements

🚀 Quick Start

Installation via npm (Recommended)

Install globally to use with any MCP client:

npm install -g plugwise-mcp-server

Or use directly with npx (no installation needed):

npx plugwise-mcp-server

Installation from Source

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

Prerequisites

Node.js 17 or higher
npm or yarn
Plugwise gateway (Adam, Anna, Smile P1, or Stretch)

Quick Test

Test the installation without real hardware using mock mode:

# Test all read operations
npm run test:read-only -- --mock

# Test protocol features
npm run test:features -- --mock

Or with real hardware:

# Set up gateway credentials
echo "PLUGWISE_HOST=192.168.1.100" > .env
echo "PLUGWISE_PASSWORD=your-gateway-password" >> .env

# Run tests
npm run test:read-only

See Quick Test Guide for more options.

Start the Server

Option 1: Standard MCP Server (15+ specialized tools)

When installed via npm:

plugwise-mcp-server

When running from source:

npm start

Option 2: AI Agent Mode (Single natural language tool)

# Interactive mode with prompt
npm run agent "List my devices"
npm run agent "Set living room to 21 degrees"

# Interactive with verbose debugging
npm run agent "What's the power usage?" -- -v

# MCP server mode (no arguments)
npm run agent

# JSON-RPC mode (for scripting)
npm run agent -- --jsonrpc
echo '{"jsonrpc":"2.0","method":"execute","params":{"instruction":"List devices"},"id":1}' | npm run agent -- --jsonrpc

See Agent Documentation and JSON-RPC Mode for details.

🔌 Adding the MCP Server to Your Client

The Plugwise MCP server can work with any MCP client that supports standard I/O (stdio) as the transport medium. Choose between:

Standard Mode: 15+ specialized tools for direct device control
Agent Mode: Single manage_plugwise tool with natural language interface

Claude Desktop

Standard Mode (15+ tools):

{
  "mcpServers": {
    "plugwise": {
      "command": "npx",
      "args": ["-y", "plugwise-mcp-server@latest"],
      "env": {
        "HUB1": "abc12345",
        "HUB1IP": "192.168.1.100",
        "HUB2": "def67890",
        "HUB2IP": "192.168.1.101"
      }
    }
  }
}

Agent Mode (natural language):

{
  "mcpServers": {
    "plugwise-agent": {
      "command": "node",
      "args": ["/path/to/plugwise/dist/cli/plugwise-agent-cli.js"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "PLUGWISE_AGENT_MODEL": "gpt-4o-mini"
      }
    }
  }
}

Cline

To configure Cline to use the Plugwise MCP server, edit the cline_mcp_settings.json file. You can open or create this file by clicking the MCP Servers icon at the top of the Cline pane, then clicking the Configure MCP Servers button.

{
  "mcpServers": {
    "plugwise": {
      "command": "npx",
      "args": ["-y", "plugwise-mcp-server@latest"],
      "disabled": false,
      "env": {
        "HUB1": "abc12345",
        "HUB1IP": "192.168.1.100",
        "HUB2": "def67890",
        "HUB2IP": "192.168.1.101"
      }
    }
  }
}

Cursor

To configure Cursor to use the Plugwise MCP server, edit either the file .cursor/mcp.json (to configure only a specific project) or the file ~/.cursor/mcp.json (to make the MCP server available in all projects):

{
  "mcpServers": {
    "plugwise": {
      "command": "npx",
      "args": ["-y", "plugwise-mcp-server@latest"],
      "env": {
        "HUB1": "abc12345",
        "HUB1IP": "192.168.1.100",
        "HUB2": "def67890",
        "HUB2IP": "192.168.1.101"
      }
    }
  }
}

Visual Studio Code Copilot

To configure a single project, edit the .vscode/mcp.json file in your workspace:

{
  "servers": {
    "plugwise": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "plugwise-mcp-server@latest"],
      "env": {
        "HUB1": "abc12345",
        "HUB1IP": "192.168.1.100",
        "HUB2": "def67890",
        "HUB2IP": "192.168.1.101"
      }
    }
  }
}

To make the server available in every project you open, edit your user settings:

{
  "mcp": {
    "servers": {
      "plugwise": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "plugwise-mcp-server@latest"],
        "env": {
          "HUB1": "abc12345",
          "HUB1IP": "192.168.1.100",
          "HUB2": "def67890",
          "HUB2IP": "192.168.1.101"
        }
      }
    }
  }
}

Windsurf Editor

To configure Windsurf Editor, edit the file ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "plugwise": {
      "command": "npx",
      "args": ["-y", "plugwise-mcp-server@latest"],
      "env": {
        "HUB1": "abc12345",
        "HUB1IP": "192.168.1.100",
        "HUB2": "def67890",
        "HUB2IP": "192.168.1.101"
      }
    }
  }
}

Environment Variables

The server reads hub passwords from environment variables. You can provide these in two ways:

Option 1: MCP Configuration (Recommended) Add the env field directly to your MCP client configuration as shown in the examples above.

Option 2: .env File Create a .env file in your project root or set system-wide environment variables:

# Hub passwords (8-character codes from gateway stickers)
HUB1=abc12345
HUB2=def67890

# Optional: Known IP addresses for faster discovery and auto-loading
HUB1IP=192.168.1.100
HUB2IP=192.168.1.101

Security Note: When using the MCP configuration env field, credentials are passed securely to the server process. For enhanced security, consider using .env files which are typically excluded from version control.

Quick Test

# Automatically discover and connect to your hubs
node scripts/workflow-demo.js

📡 MCP Tools

Network Discovery

`connect`

Connect to a Plugwise gateway.

// Connect to specific hub
await mcpClient.callTool('connect', { host: '192.168.1.100' });

// Manual connection
await mcpClient.callTool('connect', { 
  host: '192.168.1.100', 
  password: 'abc12345' 
});

Device Management

`get_devices`

Get all devices and their current states.

const result = await mcpClient.callTool('get_devices', {});
// Returns all devices, zones, sensors, and their current values

Climate Control

`set_temperature`

Set thermostat temperature setpoint.

await mcpClient.callTool('set_temperature', {
  location_id: 'zone123',
  setpoint: 21.0
});

`set_preset`

Change thermostat preset mode.

await mcpClient.callTool('set_preset', {
  location_id: 'zone123',
  preset: 'away'  // Options: home, away, sleep, vacation
});

Device Control

`control_switch`

Turn switches/plugs on or off.

await mcpClient.callTool('control_switch', {
  appliance_id: 'plug123',
  state: 'on'  // 'on' or 'off'
});

Gateway Management

set_gateway_mode: Set gateway mode (home, away, vacation)
set_dhw_mode: Set domestic hot water mode (auto, boost, comfort, off)
set_regulation_mode: Set heating regulation mode
delete_notification: Clear gateway notifications
reboot_gateway: Reboot the gateway (use with caution)

MCP Resources

plugwise://devices: Access current state of all devices as a resource

MCP Prompts

setup_guide: Get comprehensive step-by-step setup instructions

🧪 Testing

Comprehensive Read-Only Test Suite

npm run test:all

This runs a complete test of all read-only MCP operations:

✅ Server health check
✅ MCP protocol initialization
✅ Network scanning for hubs
✅ Gateway connection and info retrieval
✅ Device state reading
✅ Resources and prompts

Safe: Only tests read operations, never changes device states.

See Test Documentation for details.

Complete Workflow Demo

node scripts/workflow-demo.js

This demonstrates:

✅ Network scanning with .env passwords
✅ Auto-connection without credentials
✅ Device discovery and listing
✅ Multi-hub management

Network Scanning Test

node scripts/test-network-scan.js

Full MCP Test Suite

node scripts/test-mcp-server.js

Bash Script for Hub Discovery

./scripts/find-plugwise-hub.sh

🏗️ Supported Devices

Gateways

Adam: Smart home hub with OpenTherm support (thermostat control, floor heating)
Anna: Standalone thermostat gateway
Smile P1: Energy monitoring gateway (electricity, gas, solar)
Stretch: Legacy hub for connecting Circle smart plugs

Connected Devices

Jip: Motion sensor with illuminance detection
Lisa: Radiator valve (requires hub)
Tom/Floor: Floor heating controller
Koen: Radiator valve (requires a Plug as intermediary)
Plug: Smart plug with power monitoring (Zigbee)
Aqara Plug: Third-party Zigbee smart plug
Circle: Legacy Circle/Circle+ plugs (via Stretch only)

📖 Documentation

Setup Guide - Detailed setup instructions
MCP Server Documentation - Complete API reference
Network Scanning Guide - Network discovery deep dive
Network Scanning Summary - Feature overview

🔧 Development

Development Mode

Run with hot-reload:

npm run dev

Build

Compile TypeScript to JavaScript:

npm run build

Project Structure

plugwise/
├── src/mcp/              # TypeScript source
│   ├── server.ts         # MCP server with tools
│   ├── plugwise-client.ts # Plugwise API client
│   └── plugwise-types.ts  # Type definitions
├── build/mcp/            # Compiled JavaScript
├── docs/                 # Documentation
├── scripts/              # Test scripts
│   ├── workflow-demo.js
│   ├── test-network-scan.js
│   ├── test-mcp-server.js
│   └── find-plugwise-hub.sh
├── .env                  # Hub credentials
├── package.json
└── tsconfig.json

🔐 Security

Password Storage: Store passwords in .env file only (never in code)
Git Ignore: .env is in .gitignore to prevent committing secrets
Network Security: Plugwise uses HTTP Basic Auth (not HTTPS)
- Keep gateways on secure local network
- Use VPN for remote access
- Consider separate VLAN for IoT devices
API Access: The API has full control over your heating system - restrict access accordingly

🐛 Troubleshooting

No Hubs Found During Scan

Check .env file has HUB1, HUB2, etc. defined
Verify passwords are correct (case-sensitive, check gateway sticker)
Ensure gateways are powered on and connected to network
Confirm you're on the same network as the hubs
Try: ping <gateway_ip> to test connectivity

Connection Errors

Verify IP address is correct
Check firewall isn't blocking po

…

Plugwise

Installation

Configuration

How to use

README

Plugwise MCP Server

✨ Key Features

🚀 Quick Start

Installation via npm (Recommended)

Installation from Source

Prerequisites

Quick Test

Start the Server

🔌 Adding the MCP Server to Your Client

Claude Desktop

Cline

Cursor

Visual Studio Code Copilot

Windsurf Editor

Environment Variables

Quick Test

📡 MCP Tools

Network Discovery

connect

Device Management

get_devices

Climate Control

set_temperature

set_preset

Device Control

control_switch

Gateway Management

MCP Resources

MCP Prompts

🧪 Testing

Comprehensive Read-Only Test Suite

Complete Workflow Demo

Network Scanning Test

Full MCP Test Suite

Bash Script for Hub Discovery

🏗️ Supported Devices

Gateways

Connected Devices

📖 Documentation

🔧 Development

Development Mode

Build

Project Structure

🔐 Security

🐛 Troubleshooting

No Hubs Found During Scan

Connection Errors

You might also like

`connect`

`get_devices`

`set_temperature`

`set_preset`

`control_switch`