Fibaro HC3

What is mcp-server-hc3?

mcp-server-hc3 is a Model Context Protocol (MCP) server designed to seamlessly integrate Large Language Model (LLM) applications, such as Claude Desktop, with Fibaro Home Center 3 (HC3) smart home systems. It acts as a bridge, allowing AI assistants to directly control Fibaro HC3 devices and automation scenes through natural language commands.

How to use mcp-server-hc3?

Installation and Configuration

Install Dependencies: Run npm install.
Build: Run npm run build.
Configure: Create a .env file with your HC3 host, username, and password. Optional configurations include HC3 port, server timeout, logging level, and MCP transport type (stdio or http).
Run: Start the server using npm start.

Integration with MCP Clients

Claude Desktop (STDIO Transport): Add a specific JSON configuration to your Claude Desktop MCP configuration file, pointing to the dist/index.js of mcp-server-hc3 and providing necessary environment variables.
HTTP-based MCP Clients: Configure MCP_TRANSPORT_TYPE=http in your .env file. The server will be available at http://localhost:3000/mcp. Authentication via x-api-key header is highly recommended.

Docker Deployment

For containerized environments, use Docker Compose. Set up an .env file for Docker with required HC3 and MCP configurations, then run docker-compose up -d to build and start the container. Integration with Claude Desktop or custom MCP clients via Docker involves configuring the client to connect to the Docker container's HTTP endpoint.

Key Features of mcp-server-hc3

mcp-server-hc3 provides a comprehensive set of tools (actions) for managing your Fibaro HC3 system:

Room Management: list_rooms (get all rooms), get_room (get detailed room information).
Device Control: list_devices (list devices with filtering), get_device (get comprehensive device details), call_device_action (execute device actions like turnOn, turnOff, toggle, setValue).
Scene Management: list_scenes (get all scenes), get_scene (get detailed scene information), execute_scene (execute a scene asynchronously or synchronously), kill_scene (stop a running scene).
System Tools: test_connection (test connectivity to your HC3 system).

Use Cases of mcp-server-hc3

This project enables various smart home automation scenarios through natural language commands via AI assistants:

Voice Control: "Turn on all lights in the living room."
Device Manipulation: "Toggle main kitchen lamp," "Set bedroom lamp to 10%."
Scene Execution: "Execute my goodnight scene."
AI-driven Automation: Allows LLM applications to directly interact with and control your Fibaro HC3 smart home devices and automation routines.

FAQ about mcp-server-hc3

Is this project officially affiliated with Fibaro? No, this is a community-developed solution and is not affiliated with, endorsed by, or sponsored by Fibaro or Fibar Group S.A.
What are the required environment variables for configuration? HC3_HOST, HC3_USERNAME, and HC3_PASSWORD are required. Optional variables include HC3_PORT, MCP_TRANSPORT_TYPE, MCP_HTTP_HOST, MCP_HTTP_PORT, and MCP_HTTP_API_KEY.
How can I debug and develop with mcp-server-hc3? The npm run dev command includes an MCP Inspector, providing an interactive web interface at http://localhost:6274/ for testing MCP tools.
What Fibaro HC3 APIs does this server implement? It implements the official Fibaro HC3 REST API for Rooms, Devices, and Scenes.

MCP Server for Fibaro HC3

A Model Context Protocol (MCP) server that provides seamless integration between LLM applications (like Claude Desktop) and Fibaro Home Center 3 smart home systems.

⚠️ Disclaimer

This is a community-developed solution.
This project is not affiliated with, endorsed by, or sponsored by Fibaro or Fibar Group S.A.
"Fibaro" and all related names and trademarks are the property of their respective owners.
This software is provided as-is, without any warranties or guarantees.
Use at your own risk. The author takes no responsibility for any damage or issues caused by using this code.

🏠 What is this?

This MCP server enables AI assistants to directly control your Fibaro HC3 smart home devices and automation scenes. You can ask natural language questions like:

"Turn on all lights in the living room"
"Toggle main kitchen lamp"
"Execute my goodnight scene"
"Set bedroom lamp to 10%"

✨ Features

🛠️ Tools (Actions)

Room Management

list_rooms - Get all rooms in your HC3 system
get_room - Get detailed information about a specific room

Device Control

list_devices - List devices with optional filtering
get_device - Get comprehensive device details
call_device_action - Execute any device action (turnOn, turnOff, toggle, setValue, etc.)

Scene Management

list_scenes - Get all scenes in your HC3 system
get_scene - Get detailed information about a specific scene
execute_scene - Execute a scene (async or sync)
kill_scene - Stop a running scene

System Tools

test_connection - Test connectivity to your HC3 system

🚀 Quick Start

1. Installation

# Install dependencies
npm install

# Build the TypeScript code
npm run build

2. Configuration

Create a .env file in the project root:

# Required
HC3_HOST=192.168.1.100          # Your HC3 IP address
HC3_USERNAME=admin               # Your HC3 username
HC3_PASSWORD=your_password       # Your HC3 password

# Optional
HC3_PORT=80                      # HC3 port (default: 80)
SERVER_TIMEOUT=10000                # Request timeout in ms (default: 10000)
LOG_LEVEL=info                      # Logging level (default: info)

# MCP Transport Configuration
MCP_TRANSPORT_TYPE=stdio            # Transport type: 'stdio' or 'http' (default: stdio)
MCP_HTTP_HOST=localhost             # HTTP server host (default: localhost)
MCP_HTTP_PORT=3000                  # HTTP server port (default: 3000)
MCP_HTTP_API_KEY=your-api-key-here  # API key for HTTP authentication (used only for 'http' transport type)

⚠️ Important: Never commit your .env file to version control!

3. Running

npm start

4. Integration with MCP Clients

Claude Desktop (STDIO Transport)

Add this to your Claude Desktop MCP configuration file:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-server-hc3": {
      "command": "node",
      "args": ["/path/to/your/mcp-server-hc3/dist/index.js"],
      "env": {
        "HC3_HOST": "192.168.1.100",
        "HC3_USERNAME": "admin",
        "HC3_PASSWORD": "your_password",
        "HC3_PORT": "80",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

HTTP-based MCP Clients

For clients that support HTTP transport, configure the server with HTTP transport:

# Configure in .env file:
MCP_TRANSPORT_TYPE=http
MCP_HTTP_HOST=localhost
MCP_HTTP_PORT=3000
MCP_HTTP_API_KEY=your-api-key-here

# Start server
npm start

The server will be available at:

Endpoint: http://localhost:3000/mcp
Methods:
- POST /mcp - Client-to-server requests
- GET /mcp - Server-to-client notifications (SSE)
- DELETE /mcp - Session termination

🔐 Authentication: When using HTTP transport, it's highly recommended to include the x-api-key header in your requests. The value should match the MCP_HTTP_API_KEY from your configuration.

🐳 Docker Deployment

For easy deployment and containerized environments, you can run the MCP server using Docker.

Quick Start with Docker

Environment File Setup

Example .env configuration for Docker:

# MCP Server Configuration
MCP_TRANSPORT_TYPE=http
MCP_HTTP_HOST=0.0.0.0
MCP_HTTP_PORT=3000
MCP_HTTP_API_KEY=your-api-key-here

# Fibaro HC3 Configuration (Required)
HC3_HOST=192.168.1.100
HC3_USERNAME=admin
HC3_PASSWORD=your_secure_password
HC3_PORT=80

# Server Configuration
SERVER_TIMEOUT=10000
LOG_LEVEL=info

Build and Run with Docker Compose

# Build and start the container
docker-compose up -d

Integration with MCP Clients (Docker)

Claude Desktop with Docker

Configure Claude Desktop to connect to the Docker container:

{
  "mcpServers": {
    "mcp-server-hc3": {
      "command": "curl",
      "args": ["-X", "POST", "-H", "Content-Type: application/json", "-H", "x-api-key: your-api-key-here", "http://localhost:3000/mcp"]
    }
  }
}

🔐 Authentication: Include the x-api-key header with the value matching your MCP_HTTP_API_KEY configuration for secure access.

Custom MCP Client Integration

Connect to the Docker container via HTTP:

Endpoint: http://localhost:3000/mcp
Transport: HTTP-based MCP protocol
Headers:
- Content-Type: application/json
- x-api-key: your-api-key-here (highly recommended, should match MCP_HTTP_API_KEY)

🛠️ Development

Environment Variables

Fibaro HC3 Configuration

Variable	Required	Default	Description
`HC3_HOST`	✅	-	HC3 IP address or hostname
`HC3_USERNAME`	✅	-	HC3 username
`HC3_PASSWORD`	✅	-	HC3 password
`HC3_PORT`	❌	`80`	HC3 HTTP port

MCP Transport Configuration

Variable	Required	Default	Description
`MCP_TRANSPORT_TYPE`	❌	`stdio`	Transport type: 'stdio' or 'http'
`MCP_HTTP_HOST`	❌	`localhost`	HTTP server bind address
`MCP_HTTP_PORT`	❌	`3000`	HTTP server port
`MCP_HTTP_API_KEY`	❌	-	API key for HTTP authentication

Available Scripts

npm run build          # Build TypeScript code
npm run watch          # Build and watch for changes
npm start              # Start the server
npm run dev            # Development mode with MCP Inspector

MCP Inspector

The npm run dev command includes the MCP Inspector for development and debugging. This provides an interactive web interface at http://localhost:6274/ to test MCP tools.

Project Structure

src/
├── index.ts            # Main entry point
├── config/
│   └── index.ts        # Configuration management
├── mcp/
│   ├── server.ts       # MCP server setup and transport
│   ├── http.ts         # HTTP transport implementation
│   └── types.ts        # MCP transport types
├── fibaro/
│   ├── client.ts       # Fibaro HC3 API client
│   ├── room.api.ts     # Room API implementation
│   ├── device.api.ts   # Device API implementation
│   ├── scene.api.ts    # Scene API implementation
│   └── types.ts        # Fibaro API types
└── tools/
    ├── index.ts        # Main tools setup
    ├── common.ts       # Shared utilities
    ├── room.tools.ts   # Room management tools
    ├── device.tools.ts # Device control tools
    ├── scene.tools.ts  # Scene management tools
    └── system.tools.ts # System tools

🏗️ API Reference

Fibaro HC3 REST API

This server implements the official Fibaro HC3 REST API:

Rooms API: /api/rooms
Devices API: /api/devices
Scenes API: /api/scenes

📝 License

MIT - see LICENSE file for details.

Ready to make your smart home smarter with AI! 🎉

Fibaro HC3 Overview