MCP Server For Fibaro HC3

What is MCP Server For Fibaro HC3 about?

Enables AI assistants (e.g., Claude Desktop) to interact directly with a Fibaro Home Center 3 system, allowing natural‑language commands to list, query and control rooms, devices, and scenes.

How to use MCP Server For Fibaro HC3?

Install the project dependencies with npm install and build the TypeScript code using npm run build (or run it directly via npx).
Configure a .env file with your Fibaro credentials and optional transport settings (STDIO or HTTP).
Start the server with npm start. For development, npm run dev launches the MCP Inspector at http://localhost:6274/.
Connect your MCP client (Claude Desktop, HTTP‑based client, Docker container, etc.) using the chosen transport. For STDIO, point the client to the compiled dist/index.js. For HTTP, send POST requests to http://<host>:<port>/mcp with the x‑api‑key header if configured.

Key Features

Room Management: list_rooms, get_room.
Device Control: list_devices, get_device, call_device_action (turnOn, turnOff, toggle, setValue, …).
Scene Management: list_scenes, get_scene, execute_scene, kill_scene.
System Tool: test_connection to verify HC3 connectivity.
Transport Options: STDIO for local AI clients or HTTP with optional API‑key authentication.
Docker Support: Ready‑to‑run container with environment‑file configuration.
MCP Inspector: Web UI for testing tools and debugging.

Use Cases

Voice‑like natural‑language control of lights, blinds, thermostats, etc., from an AI assistant.
Automating nightly or away‑mode routines by invoking Fibaro scenes via chat commands.
Integrating smart‑home status into larger AI workflows (e.g., “Is the front door locked?”).
Providing developers a sandbox to prototype AI‑driven home automation without writing Fibaro API code.

FAQ

Q: Do I need a Fibaro HC3 account to run this server? A: Yes. You must supply a valid HC3_HOST, HC3_USERNAME and HC3_PASSWORD.

Q: Can I run the server behind a reverse proxy? A: When using HTTP transport, bind MCP_HTTP_HOST to 0.0.0.0 and expose the port through your proxy.

Q: Is the server secure? A: The HTTP transport supports an x‑api‑key header. Keep your .env file out of version control and use TLS termination at the proxy if needed.

Q: How do I add custom tools? A: Extend the tools/ directory and register the new tool in src/tools/index.ts; then rebuild the project.

Q: What Node.js version is required? A: The project targets Node 14+ (LTS).

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! 🎉

MCP Server For Fibaro HC3