plugwise-mcp-server
Advanced tools
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.
When installed via npm:
plugwise-mcp-server
When running from source:
npm start
Server runs at:
http://localhost:3000/mcphttp://localhost:3000/healthThe 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:
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"],
"env": {
"HUB1": "abc12345",
"HUB1IP": "192.168.1.100",
"HUB2": "def67890",
"HUB2IP": "192.168.1.101"
}
}
}
}
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 <gateway_ip> to test connectivitycurl http://<ip>/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
FAQs
MCP server for Plugwise integration
We found that plugwise-mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.