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_plugwisetool 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 modedelete_notification: Clear gateway notificationsreboot_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
.envfile only (never in code) - Git Ignore:
.envis in.gitignoreto 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
.envfile hasHUB1,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 port 80
- Test with manual connection:
curl http://<ip>/core/domain_objects - Ensure gateway isn't overloaded with requests
🤝 Integration Examples
Using with Claude Code
claude mcp add --transport http plugwise-server http://localhost:3000/mcp
Using with VS Code Copilot
Add to .vscode/mcp.json:
{
"mcpServers": {
"plugwise": {
"type": "http",
"url": "http://localhost:3000/mcp"
}
}
}
Using MCP Inspector
npx @modelcontextprotocol/inspector
Connect to: http://localhost:3000/mcp
📊 Example Workflows
Morning Routine
// Connect to hub
await mcpClient.callTool('connect', { host: '192.168.1.100' });
// Set home mode
await mcpClient.callTool('set_preset', {
location_id: 'living_room',
preset: 'home'
});
// Warm up bathroom
await mcpClient.callTool('set_temperature', {
location_id: 'bathroom',
setpoint: 22.0
});
Energy Monitoring
const devices = await mcpClient.callTool('get_devices', {});
for (const [id, device] of Object.entries(devices.data)) {
if (device.sensors?.electricity_consumed) {
console.log(`${device.name}: ${device.sensors.electricity_consumed}W`);
}
}
Multi-Hub Management
// List all hubs
const hubsList = await mcpClient.callTool('list_hubs', {});
// Get devices from each hub
for (const hub of hubsList.hubs) {
await mcpClient.callTool('connect', { host: hub.ip });
const devices = await mcpClient.callTool('get_devices', {});
console.log(`Hub ${hub.ip}: ${Object.keys(devices.data).length} devices`);
}
📚 Documentation
Migration Guides
- Structure Migration Plan - Complete plan for restructuring project
- Structure Comparison - Visual comparison of architectures
- Migration Checklist - Step-by-step migration checklist
- Migration Summary - Quick reference summary
Architecture & Design
- Architecture Diagram - System architecture overview
- Code Organization - Project structure and conventions
- Reorganization Overview - Historical reorganization notes
Implementation Guides
- Autoload Hubs - Automatic hub loading implementation
- Network Scanning - Network discovery implementation
- Temperature Tools - Temperature control features
- Sensor & Switch Parsing - Device parsing logic
Quick References
- Quick Reference - Common commands and patterns
- Autoload Quick Reference - Autoload feature guide
- Temperature Tools Quick Reference - Temperature API guide
Testing & Development
- Quick Test Guide - Fast start testing guide
- Test Scripts Documentation - Comprehensive testing documentation
- Test All Script - HTTP-based testing guide
- Multi-Hub Testing - Testing with multiple hubs
- List Devices Script - Device enumeration guide
Publishing & Setup
- Publishing Guide - How to publish to npm
- Setup Guide - Initial setup instructions
- Publish Checklist - Pre-publish verification
🌟 Credits
Based on the excellent python-plugwise library.
Architectural patterns inspired by sonos-ts-mcp.
📄 License
MIT License - See LICENSE file for details
🚀 Version
Current version: 1.0.2
- ✅ Full MCP protocol support
- ✅ Automatic network scanning
- ✅ Multi-hub management
- ✅ Complete device control
- ✅ Comprehensive documentation
- ✅ Structure migration planning