A TypeScript-based Model Context Protocol (MCP) server for Plugwise smart home integration with automatic network discovery. - 🤖 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
Add this skill
npx mdskills install Tommertom/plugwise-mcpComprehensive smart home integration with excellent docs, multi-mode operation, and robust discovery features
A TypeScript-based Model Context Protocol (MCP) server for Plugwise smart home integration with automatic network discovery.
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
git clone https://github.com/Tommertom/plugwise-mcp-server.git
cd plugwise-mcp-server
npm install
npm run build
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.
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.
The Plugwise MCP server can work with any MCP client that supports standard I/O (stdio) as the transport medium. Choose between:
manage_plugwise tool with natural language interfaceStandard 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"
}
}
}
}
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"
}
}
}
}
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"
}
}
}
}
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"
}
}
}
}
}
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"
}
}
}
}
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.
# Automatically discover and connect to your hubs
node scripts/workflow-demo.js
connectConnect 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'
});
get_devicesGet all devices and their current states.
const result = await mcpClient.callTool('get_devices', {});
// Returns all devices, zones, sensors, and their current values
set_temperatureSet thermostat temperature setpoint.
await mcpClient.callTool('set_temperature', {
location_id: 'zone123',
setpoint: 21.0
});
set_presetChange thermostat preset mode.
await mcpClient.callTool('set_preset', {
location_id: 'zone123',
preset: 'away' // Options: home, away, sleep, vacation
});
control_switchTurn switches/plugs on or off.
await mcpClient.callTool('control_switch', {
appliance_id: 'plug123',
state: 'on' // 'on' or 'off'
});
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)plugwise://devices: Access current state of all devices as a resourcesetup_guide: Get comprehensive step-by-step setup instructionsnpm run test:all
This runs a complete test of all read-only MCP operations:
Safe: Only tests read operations, never changes device states.
See Test Documentation for details.
node scripts/workflow-demo.js
This demonstrates:
node scripts/test-network-scan.js
node scripts/test-mcp-server.js
./scripts/find-plugwise-hub.sh
Run with hot-reload:
npm run dev
Compile TypeScript to JavaScript:
npm run build
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
.env file only (never in code).env is in .gitignore to prevent committing secrets.env file has HUB1, HUB2, etc. definedping to test connectivitycurl http:///core/domain_objectsclaude mcp add --transport http plugwise-server http://localhost:3000/mcp
Add to .vscode/mcp.json:
{
"mcpServers": {
"plugwise": {
"type": "http",
"url": "http://localhost:3000/mcp"
}
}
}
npx @modelcontextprotocol/inspector
Connect to: http://localhost:3000/mcp
// 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
});
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`);
}
}
// 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`);
}
Based on the excellent python-plugwise library.
Architectural patterns inspired by sonos-ts-mcp.
MIT License - See LICENSE file for details
Current version: 1.0.2
Install via CLI
npx mdskills install Tommertom/plugwise-mcpPlugwise MCP Server is a free, open-source AI agent skill. A TypeScript-based Model Context Protocol (MCP) server for Plugwise smart home integration with automatic network discovery. - 🤖 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
Install Plugwise MCP Server with a single command:
npx mdskills install Tommertom/plugwise-mcpThis downloads the skill files into your project and your AI agent picks them up automatically.
Plugwise MCP Server works with Claude Code, Claude Desktop, Cursor, Vscode Copilot, Windsurf, Continue Dev, Gemini Cli, Amp, Roo Code, Goose. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.