Tommertom/plugwise-mcp

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:
Or use directly with npx (no installation needed):
Installation from Source
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:
Or with real hardware:
See Quick Test Guide for more options.
Start the Server
**Option 1: Standard MCP Server** (15+ specialized tools)
When installed via npm:
When running from source:
**Option 2: AI Agent Mode** (Single natural language tool)
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_plugwise tool with natural language interface
Claude Desktop
**Standard Mode** (15+ tools):
**Agent Mode** (natural language):
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.
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):
Visual Studio Code Copilot
To configure a single project, edit the .vscode/mcp.json file in your workspace:
To make the server available in every project you open, edit your user settings:
Windsurf Editor
To configure Windsurf Editor, edit the file ~/.codeium/windsurf/mcp_config.json:
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:
**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
📡 MCP Tools
Network Discovery
connect
Connect to a Plugwise gateway.
Device Management
get_devices
Get all devices and their current states.
Climate Control
set_temperature
Set thermostat temperature setpoint.
set_preset
Change thermostat preset mode.
Device Control
control_switch
Turn switches/plugs 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