Plugwise MCP Server

1# Plugwise MCP Server
2 
3A TypeScript-based Model Context Protocol (MCP) server for Plugwise smart home integration with automatic network discovery.
4 
5## ✨ Key Features
6 
7- 🤖 **AI Agent Mode**: Natural language control via built-in AI agent
8- 📡 **JSON-RPC Support**: Programmatic API for scripting and automation
9- 🔍 **Automatic Network Scanning**: Discovers all Plugwise hubs on your network
10- 🔐 **Credential Management**: Stores hub passwords securely from .env file
11- 🔌 **Device Control**: Control thermostats, switches, and smart plugs
12- 🌡️ **Temperature Management**: Set temperatures, presets, and schedules
13- 📊 **Energy Monitoring**: Read power consumption and sensor data
14- 🏠 **Multi-Hub Support**: Manage multiple gateways simultaneously
15- 🔄 **Real-time Updates**: Get current device states and measurements
16 
17## 🚀 Quick Start
18 
19### Installation via npm (Recommended)
20 
21Install globally to use with any MCP client:
22 
23```bash
24npm install -g plugwise-mcp-server
25```
26 
27Or use directly with npx (no installation needed):
28 
29```bash
30npx plugwise-mcp-server
31```
32 
33### Installation from Source
34 
35```bash
36git clone https://github.com/Tommertom/plugwise-mcp-server.git
37cd plugwise-mcp-server
38npm install
39npm run build
40```
41 
42### Prerequisites
43- Node.js 17 or higher
44- npm or yarn
45- Plugwise gateway (Adam, Anna, Smile P1, or Stretch)
46 
47### Quick Test
48 
49Test the installation without real hardware using mock mode:
50 
51```bash
52# Test all read operations
53npm run test:read-only -- --mock
54 
55# Test protocol features
56npm run test:features -- --mock
57```
58 
59Or with real hardware:
60 
61```bash
62# Set up gateway credentials
63echo "PLUGWISE_HOST=192.168.1.100" > .env
64echo "PLUGWISE_PASSWORD=your-gateway-password" >> .env
65 
66# Run tests
67npm run test:read-only
68```
69 
70See [Quick Test Guide](docs/quick-test-guide.md) for more options.
71 
72### Start the Server
73 
74**Option 1: Standard MCP Server** (15+ specialized tools)
75 
76When installed via npm:
77 
78```bash
79plugwise-mcp-server
80```
81 
82When running from source:
83 
84```bash
85npm start
86```
87 
88**Option 2: AI Agent Mode** (Single natural language tool)
89 
90```bash
91# Interactive mode with prompt
92npm run agent "List my devices"
93npm run agent "Set living room to 21 degrees"
94 
95# Interactive with verbose debugging
96npm run agent "What's the power usage?" -- -v
97 
98# MCP server mode (no arguments)
99npm run agent
100 
101# JSON-RPC mode (for scripting)
102npm run agent -- --jsonrpc
103echo '{"jsonrpc":"2.0","method":"execute","params":{"instruction":"List devices"},"id":1}' | npm run agent -- --jsonrpc
104```
105 
106See [Agent Documentation](docs/agent-mcp-server.md) and [JSON-RPC Mode](docs/jsonrpc-mode.md) for details.
107 
108## 🔌 Adding the MCP Server to Your Client
109 
110The Plugwise MCP server can work with any MCP client that supports standard I/O (stdio) as the transport medium. Choose between:
111 
112- **Standard Mode**: 15+ specialized tools for direct device control
113- **Agent Mode**: Single `manage_plugwise` tool with natural language interface
114 
115### Claude Desktop
116 
117**Standard Mode** (15+ tools):
118 
119```json
120{
121  "mcpServers": {
122    "plugwise": {
123      "command": "npx",
124      "args": ["-y", "plugwise-mcp-server@latest"],
125      "env": {
126        "HUB1": "abc12345",
127        "HUB1IP": "192.168.1.100",
128        "HUB2": "def67890",
129        "HUB2IP": "192.168.1.101"
130      }
131    }
132  }
133}
134```
135 
136**Agent Mode** (natural language):
137 
138```json
139{
140  "mcpServers": {
141    "plugwise-agent": {
142      "command": "node",
143      "args": ["/path/to/plugwise/dist/cli/plugwise-agent-cli.js"],
144      "env": {
145        "OPENAI_API_KEY": "sk-...",
146        "PLUGWISE_AGENT_MODEL": "gpt-4o-mini"
147      }
148    }
149  }
150}
151```
152 
153### Cline
154 
155To 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.
156 
157```json
158{
159  "mcpServers": {
160    "plugwise": {
161      "command": "npx",
162      "args": ["-y", "plugwise-mcp-server@latest"],
163      "disabled": false,
164      "env": {
165        "HUB1": "abc12345",
166        "HUB1IP": "192.168.1.100",
167        "HUB2": "def67890",
168        "HUB2IP": "192.168.1.101"
169      }
170    }
171  }
172}
173```
174 
175### Cursor
176 
177To 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):
178 
179```json
180{
181  "mcpServers": {
182    "plugwise": {
183      "command": "npx",
184      "args": ["-y", "plugwise-mcp-server@latest"],
185      "env": {
186        "HUB1": "abc12345",
187        "HUB1IP": "192.168.1.100",
188        "HUB2": "def67890",
189        "HUB2IP": "192.168.1.101"
190      }
191    }
192  }
193}
194```
195 
196### Visual Studio Code Copilot
197 
198To configure a single project, edit the `.vscode/mcp.json` file in your workspace:
199 
200```json
201{
202  "servers": {
203    "plugwise": {
204      "type": "stdio",
205      "command": "npx",
206      "args": ["-y", "plugwise-mcp-server@latest"],
207      "env": {
208        "HUB1": "abc12345",
209        "HUB1IP": "192.168.1.100",
210        "HUB2": "def67890",
211        "HUB2IP": "192.168.1.101"
212      }
213    }
214  }
215}
216```
217 
218To make the server available in every project you open, edit your user settings:
219 
220```json
221{
222  "mcp": {
223    "servers": {
224      "plugwise": {
225        "type": "stdio",
226        "command": "npx",
227        "args": ["-y", "plugwise-mcp-server@latest"],
228        "env": {
229          "HUB1": "abc12345",
230          "HUB1IP": "192.168.1.100",
231          "HUB2": "def67890",
232          "HUB2IP": "192.168.1.101"
233        }
234      }
235    }
236  }
237}
238```
239 
240### Windsurf Editor
241 
242To configure Windsurf Editor, edit the file `~/.codeium/windsurf/mcp_config.json`:
243 
244```json
245{
246  "mcpServers": {
247    "plugwise": {
248      "command": "npx",
249      "args": ["-y", "plugwise-mcp-server@latest"],
250      "env": {
251        "HUB1": "abc12345",
252        "HUB1IP": "192.168.1.100",
253        "HUB2": "def67890",
254        "HUB2IP": "192.168.1.101"
255      }
256    }
257  }
258}
259```
260 
261### Environment Variables
262 
263The server reads hub passwords from environment variables. You can provide these in two ways:
264 
265**Option 1: MCP Configuration (Recommended)**
266Add the `env` field directly to your MCP client configuration as shown in the examples above.
267 
268**Option 2: .env File**
269Create a `.env` file in your project root or set system-wide environment variables:
270 
271```env
272# Hub passwords (8-character codes from gateway stickers)
273HUB1=abc12345
274HUB2=def67890
275 
276# Optional: Known IP addresses for faster discovery and auto-loading
277HUB1IP=192.168.1.100
278HUB2IP=192.168.1.101
279```
280 
281**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.
282 
283### Quick Test
284 
285```bash
286# Automatically discover and connect to your hubs
287node scripts/workflow-demo.js
288```
289 
290## 📡 MCP Tools
291 
292### Network Discovery
293 
294#### `connect`
295Connect to a Plugwise gateway.
296 
297```javascript
298// Connect to specific hub
299await mcpClient.callTool('connect', { host: '192.168.1.100' });
300 
301// Manual connection
302await mcpClient.callTool('connect', { 
303  host: '192.168.1.100', 
304  password: 'abc12345' 
305});
306```
307 
308### Device Management
309 
310#### `get_devices`
311Get all devices and their current states.
312 
313```javascript
314const result = await mcpClient.callTool('get_devices', {});
315// Returns all devices, zones, sensors, and their current values
316```
317 
318### Climate Control
319 
320#### `set_temperature`
321Set thermostat temperature setpoint.
322 
323```javascript
324await mcpClient.callTool('set_temperature', {
325  location_id: 'zone123',
326  setpoint: 21.0
327});
328```
329 
330#### `set_preset`
331Change thermostat preset mode.
332 
333```javascript
334await mcpClient.callTool('set_preset', {
335  location_id: 'zone123',
336  preset: 'away'  // Options: home, away, sleep, vacation
337});
338```
339 
340### Device Control
341 
342#### `control_switch`
343Turn switches/plugs on or off.
344 
345```javascript
346await mcpClient.callTool('control_switch', {
347  appliance_id: 'plug123',
348  state: 'on'  // 'on' or 'off'
349});
350```
351 
352### Gateway Management
353 
354- **`set_gateway_mode`**: Set gateway mode (home, away, vacation)
355- **`set_dhw_mode`**: Set domestic hot water mode (auto, boost, comfort, off)
356- **`set_regulation_mode`**: Set heating regulation mode
357- **`delete_notification`**: Clear gateway notifications
358- **`reboot_gateway`**: Reboot the gateway (use with caution)
359 
360### MCP Resources
361 
362- **`plugwise://devices`**: Access current state of all devices as a resource
363 
364### MCP Prompts
365 
366- **`setup_guide`**: Get comprehensive step-by-step setup instructions
367 
368## 🧪 Testing
369 
370### Comprehensive Read-Only Test Suite
371 
372```bash
373npm run test:all
374```
375 
376This runs a complete test of all read-only MCP operations:
377- ✅ Server health check
378- ✅ MCP protocol initialization
379- ✅ Network scanning for hubs
380- ✅ Gateway connection and info retrieval
381- ✅ Device state reading
382- ✅ Resources and prompts
383 
384**Safe**: Only tests read operations, never changes device states.
385 
386See [Test Documentation](docs/test-all-script.md) for details.
387 
388### Complete Workflow Demo
389 
390```bash
391node scripts/workflow-demo.js
392```
393 
394This demonstrates:
3951. ✅ Network scanning with .env passwords
3962. ✅ Auto-connection without credentials
3973. ✅ Device discovery and listing
3984. ✅ Multi-hub management
399 
400### Network Scanning Test
401 
402```bash
403node scripts/test-network-scan.js
404```
405 
406### Full MCP Test Suite
407 
408```bash
409node scripts/test-mcp-server.js
410```
411 
412### Bash Script for Hub Discovery
413 
414```bash
415./scripts/find-plugwise-hub.sh
416```
417 
418## 🏗️ Supported Devices
419 
420### Gateways
421- **Adam**: Smart home hub with OpenTherm support (thermostat control, floor heating)
422- **Anna**: Standalone thermostat gateway
423- **Smile P1**: Energy monitoring gateway (electricity, gas, solar)
424- **Stretch**: Legacy hub for connecting Circle smart plugs
425 
426### Connected Devices
427- **Jip**: Motion sensor with illuminance detection
428- **Lisa**: Radiator valve (requires hub)
429- **Tom/Floor**: Floor heating controller
430- **Koen**: Radiator valve (requires a Plug as intermediary)
431- **Plug**: Smart plug with power monitoring (Zigbee)
432- **Aqara Plug**: Third-party Zigbee smart plug
433- **Circle**: Legacy Circle/Circle+ plugs (via Stretch only)
434 
435## 📖 Documentation
436 
437- **[Setup Guide](docs/setup.md)** - Detailed setup instructions
438- **[MCP Server Documentation](docs/plugwise-mcp-server.md)** - Complete API reference
439- **[Network Scanning Guide](docs/network-scanning.md)** - Network discovery deep dive
440- **[Network Scanning Summary](docs/network-scanning-summary.md)** - Feature overview
441 
442## 🔧 Development
443 
444### Development Mode
445 
446Run with hot-reload:
447 
448```bash
449npm run dev
450```
451 
452### Build
453 
454Compile TypeScript to JavaScript:
455 
456```bash
457npm run build
458```
459 
460### Project Structure
461 
462```
463plugwise/
464├── src/mcp/              # TypeScript source
465│   ├── server.ts         # MCP server with tools
466│   ├── plugwise-client.ts # Plugwise API client
467│   └── plugwise-types.ts  # Type definitions
468├── build/mcp/            # Compiled JavaScript
469├── docs/                 # Documentation
470├── scripts/              # Test scripts
471│   ├── workflow-demo.js
472│   ├── test-network-scan.js
473│   ├── test-mcp-server.js
474│   └── find-plugwise-hub.sh
475├── .env                  # Hub credentials
476├── package.json
477└── tsconfig.json
478```
479 
480## 🔐 Security
481 
4821. **Password Storage**: Store passwords in `.env` file only (never in code)
4832. **Git Ignore**: `.env` is in `.gitignore` to prevent committing secrets
4843. **Network Security**: Plugwise uses HTTP Basic Auth (not HTTPS)
485   - Keep gateways on secure local network
486   - Use VPN for remote access
487   - Consider separate VLAN for IoT devices
4884. **API Access**: The API has full control over your heating system - restrict access accordingly
489 
490## 🐛 Troubleshooting
491 
492### No Hubs Found During Scan
493 
4941. Check `.env` file has `HUB1`, `HUB2`, etc. defined
4952. Verify passwords are correct (case-sensitive, check gateway sticker)
4963. Ensure gateways are powered on and connected to network
4974. Confirm you're on the same network as the hubs
4985. Try: `ping <gateway_ip>` to test connectivity
499 
500### Connection Errors
501 
5021. Verify IP address is correct
5032. Check firewall isn't blocking port 80
5043. Test with manual connection: `curl http://<ip>/core/domain_objects`
5054. Ensure gateway isn't overloaded with requests
506 
507## 🤝 Integration Examples
508 
509### Using with Claude Code
510 
511```bash
512claude mcp add --transport http plugwise-server http://localhost:3000/mcp
513```
514 
515### Using with VS Code Copilot
516 
517Add to `.vscode/mcp.json`:
518 
519```json
520{
521  "mcpServers": {
522    "plugwise": {
523      "type": "http",
524      "url": "http://localhost:3000/mcp"
525    }
526  }
527}
528```
529 
530### Using MCP Inspector
531 
532```bash
533npx @modelcontextprotocol/inspector
534```
535 
536Connect to: `http://localhost:3000/mcp`
537 
538## 📊 Example Workflows
539 
540### Morning Routine
541 
542```javascript
543// Connect to hub
544await mcpClient.callTool('connect', { host: '192.168.1.100' });
545 
546// Set home mode
547await mcpClient.callTool('set_preset', {
548  location_id: 'living_room',
549  preset: 'home'
550});
551 
552// Warm up bathroom
553await mcpClient.callTool('set_temperature', {
554  location_id: 'bathroom',
555  setpoint: 22.0
556});
557```
558 
559### Energy Monitoring
560 
561```javascript
562const devices = await mcpClient.callTool('get_devices', {});
563 
564for (const [id, device] of Object.entries(devices.data)) {
565  if (device.sensors?.electricity_consumed) {
566    console.log(`${device.name}: ${device.sensors.electricity_consumed}W`);
567  }
568}
569```
570 
571### Multi-Hub Management
572 
573```javascript
574// List all hubs
575const hubsList = await mcpClient.callTool('list_hubs', {});
576 
577// Get devices from each hub
578for (const hub of hubsList.hubs) {
579  await mcpClient.callTool('connect', { host: hub.ip });
580  const devices = await mcpClient.callTool('get_devices', {});
581  console.log(`Hub ${hub.ip}: ${Object.keys(devices.data).length} devices`);
582}
583```
584 
585## 📚 Documentation
586 
587### Migration Guides
588 
589- **[Structure Migration Plan](docs/STRUCTURE-MIGRATION-PLAN.md)** - Complete plan for restructuring project
590- **[Structure Comparison](docs/structure-comparison-diagram.md)** - Visual comparison of architectures
591- **[Migration Checklist](docs/migration-checklist.md)** - Step-by-step migration checklist
592- **[Migration Summary](docs/migration-summary.md)** - Quick reference summary
593 
594### Architecture & Design
595 
596- **[Architecture Diagram](docs/architecture-diagram.md)** - System architecture overview
597- **[Code Organization](docs/code-organization.md)** - Project structure and conventions
598- **[Reorganization Overview](docs/reorganization-overview.md)** - Historical reorganization notes
599 
600### Implementation Guides
601 
602- **[Autoload Hubs](docs/autoload-hubs.md)** - Automatic hub loading implementation
603- **[Network Scanning](docs/network-scanning.md)** - Network discovery implementation
604- **[Temperature Tools](docs/temperature-tools-implementation.md)** - Temperature control features
605- **[Sensor & Switch Parsing](docs/sensor-switch-parsing-implementation.md)** - Device parsing logic
606 
607### Quick References
608 
609- **[Quick Reference](docs/quick-reference.md)** - Common commands and patterns
610- **[Autoload Quick Reference](docs/autoload-quickref.md)** - Autoload feature guide
611- **[Temperature Tools Quick Reference](docs/temperature-tools-quick-reference.md)** - Temperature API guide
612 
613### Testing & Development
614 
615- **[Quick Test Guide](docs/quick-test-guide.md)** - Fast start testing guide
616- **[Test Scripts Documentation](docs/test-scripts.md)** - Comprehensive testing documentation
617- **[Test All Script](docs/test-all-script.md)** - HTTP-based testing guide
618- **[Multi-Hub Testing](docs/multi-hub-testing.md)** - Testing with multiple hubs
619- **[List Devices Script](docs/list-devices-script.md)** - Device enumeration guide
620 
621### Publishing & Setup
622 
623- **[Publishing Guide](docs/publishing-guide.md)** - How to publish to npm
624- **[Setup Guide](docs/setup.md)** - Initial setup instructions
625- **[Publish Checklist](docs/PUBLISH-CHECKLIST.md)** - Pre-publish verification
626 
627## 🌟 Credits
628 
629Based on the excellent [python-plugwise](https://github.com/plugwise/python-plugwise) library.
630 
631Architectural patterns inspired by [sonos-ts-mcp](https://github.com/Tommertom/sonos-ts-mcp).
632 
633## 📄 License
634 
635MIT License - See LICENSE file for details
636 
637## 🚀 Version
638 
639Current version: **1.0.2**
640 
641- ✅ Full MCP protocol support
642- ✅ Automatic network scanning
643- ✅ Multi-hub management
644- ✅ Complete device control
645- ✅ Comprehensive documentation
646- ✅ Structure migration planning
647