Skip to main content
Glama

Plugwise MCP Server

by Tommertom
GitHub
TypeScript
MIT License
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Plugwise MCP Server

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

✨ Key Features

  • 🔍 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

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

Start the Server

When installed via npm:

plugwise-mcp-server

When running from source:

npm start

Server runs at:

  • MCP Endpoint: http://localhost:3000/mcp

  • Health Check: http://localhost:3000/health

🔌 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. Here are specific instructions for some popular tools:

Claude Desktop

To configure Claude Desktop to use the Plugwise MCP server, edit the claude_desktop_config.json file. You can open or create this file from the Claude > Settings menu. Select the Developer tab, then click Edit Config.

{ "mcpServers": { "plugwise": { "command": "npx", "args": ["-y", "plugwise-mcp-server@latest"] } } }

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 } } }

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"] } } }

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"] } } }

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"] } } } }

Windsurf Editor

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

{ "mcpServers": { "plugwise": { "command": "npx", "args": ["-y", "plugwise-mcp-server@latest"] } } }

Environment Variables

The server reads hub passwords from environment variables. Create a .env file in your project root or set system-wide environment variables:

# Hub passwords (8-character codes from gateway stickers) HUB1=glmpttxf HUB2=dkcqbjkz # Optional: Known IP addresses for faster discovery and auto-loading HUB1IP=192.168.178.235 HUB2IP=192.168.178.218

Quick Test

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

📡 MCP Tools

Network Discovery

scan_network

Automatically scan your network for Plugwise hubs using passwords from .env.

await mcpClient.callTool('scan_network', {}); // Returns: { discovered: [ { name, ip, model, firmware } ], scanned_ips: 2 }

Features:

  • Tests known IPs first if HUBxIP variables are provided (instant)

  • Falls back to full network scan if needed (1-2 minutes)

  • Stores credentials automatically for later use

connect

Connect to a Plugwise gateway. After scanning, credentials are automatic!

// Auto-connect to first discovered hub await mcpClient.callTool('connect', {}); // Connect to specific hub (password from scan) await mcpClient.callTool('connect', { host: '192.168.178.235' }); // Manual connection (without scanning) await mcpClient.callTool('connect', { host: '192.168.178.235', password: 'glmpttxf' });

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:

  1. ✅ Network scanning with .env passwords

  2. ✅ Auto-connection without credentials

  3. ✅ Device discovery and listing

  4. ✅ 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

🔧 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

  1. Password Storage: Store passwords in .env file only (never in code)

  2. Git Ignore: .env is in .gitignore to prevent committing secrets

  3. 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

  4. API Access: The API has full control over your heating system - restrict access accordingly

🐛 Troubleshooting

No Hubs Found During Scan

  1. Check .env file has HUB1, HUB2, etc. defined

  2. Verify passwords are correct (case-sensitive, check gateway sticker)

  3. Ensure gateways are powered on and connected to network

  4. Confirm you're on the same network as the hubs

  5. Try: ping <gateway_ip> to test connectivity

Connection Errors

  1. Verify IP address is correct

  2. Check firewall isn't blocking port 80

  3. Test with manual connection: curl http://<ip>/core/domain_objects

  4. Ensure gateway isn't overloaded with requests

Scan Takes Too Long

  1. Add HUBxIP variables to .env for instant scanning

  2. Specify network: scan_network({ network: '192.168.1.0/24' })

  3. Check network size (scanning /16 is much slower than /24)

🤝 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

// Scan and connect await mcpClient.callTool('scan_network', {}); await mcpClient.callTool('connect', {}); // 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

// Discover all hubs const scan = await mcpClient.callTool('scan_network', {}); // Get devices from each hub for (const hub of scan.discovered) { 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`); }

🌟 Credits

Based on the excellent python-plugwise library.

📄 License

MIT License - See LICENSE file for details

🚀 Version

Current version: 1.0.0

  • ✅ Full MCP protocol support

  • ✅ Automatic network scanning

  • ✅ Multi-hub management

  • ✅ Complete device control

  • ✅ Comprehensive documentation

This server cannot be installed

-
security - not tested
-
license - not tested
-
quality - not tested

How are these scores calculated?

Enables control and monitoring of Plugwise smart home devices including thermostats, switches, and energy meters with automatic network discovery. Supports temperature control, energy monitoring, and multi-hub management through natural language commands.

  1. ✨ Key Features
    1. 🚀 Quick Start
      1. Installation via npm (Recommended)
      2. Installation from Source
      3. Prerequisites
      4. Quick Test
      5. Start the Server
    2. 🔌 Adding the MCP Server to Your Client
      1. Claude Desktop
      2. Cline
      3. Cursor
      4. Visual Studio Code Copilot
      5. Windsurf Editor
      6. Environment Variables
      7. Quick Test
    3. 📡 MCP Tools
      1. Network Discovery
      2. Device Management
      3. Climate Control
      4. Device Control
      5. Gateway Management
      6. MCP Resources
      7. MCP Prompts
    4. 🧪 Testing
      1. Comprehensive Read-Only Test Suite
      2. Complete Workflow Demo
      3. Network Scanning Test
      4. Full MCP Test Suite
      5. Bash Script for Hub Discovery
    5. 🏗️ Supported Devices
      1. Gateways
      2. Connected Devices
    6. 📖 Documentation
      1. 🔧 Development
        1. Development Mode
        2. Build
        3. Project Structure
      2. 🔐 Security
        1. 🐛 Troubleshooting
          1. No Hubs Found During Scan
          2. Connection Errors
          3. Scan Takes Too Long
        2. 🤝 Integration Examples
          1. Using with Claude Code
          2. Using with VS Code Copilot
          3. Using MCP Inspector
        3. 📊 Example Workflows
          1. Morning Routine
          2. Energy Monitoring
          3. Multi-Hub Management
        4. 🌟 Credits
          1. 📄 License
            1. 🚀 Version

              New MCP Servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/Tommertom/plugwise-mcp'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server