# ikari-software/fibaro-mcp architecture

> Architecture diagram of the GitHub repository ikari-software/fibaro-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ikari-software/fibaro-mcp
- Repository: https://github.com/ikari-software/fibaro-mcp

## Overview

Fibaro MCP Server exposes Fibaro Home Center capabilities as MCP tools: an MCP client makes requests, handlers dispatch them to the Fibaro API client or specialized feature modules, and results return through MCP. The documented feature branches include device and scene management, bulk operations, templates, Lua REPL, backups, history and analytics, energy data, automation generation, and integrations. Specialized module links are supported by the SOURCE INDEX; unsampled handler details limit certainty about some individual routes.

Main entry points: [`src/mcp-handlers.ts`](https://github.com/ikari-software/fibaro-mcp/blob/main/src/mcp-handlers.ts) (Tool handlers), [`src/automation/workflow-engine.ts`](https://github.com/ikari-software/fibaro-mcp/blob/main/src/automation/workflow-engine.ts) (Automation builder), [`src/fibaro-client.ts`](https://github.com/ikari-software/fibaro-mcp/blob/main/src/fibaro-client.ts) (Fibaro API client), [`src/index.ts`](https://github.com/ikari-software/fibaro-mcp/blob/main/src/index.ts) (Server startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP interface"]
  node_server["Server startup<br/>[index.ts]"]
  node_handlers["Tool handlers<br/>[mcp-handlers.ts]"]
end

subgraph group_core["Fibaro access"]
  node_fibaro_client["Fibaro API client<br/>[fibaro-client.ts]"]
  node_energy["Energy aggregation"]
  node_logger["Logging<br/>[logger.ts]"]
end

subgraph group_features["Home features"]
  node_bulk["Bulk device operations<br/>[bulk-operations.ts]"]
  node_bulk_query["Bulk query engine<br/>[query-engine.ts]"]
  node_backup["Backup and restore<br/>[backup-manager.ts]"]
  node_history["History manager<br/>[history-manager.ts]"]
  node_analytics["Analytics engine"]
  node_templates["Scene templates"]
  node_template_data["Template library"]
  node_repl["Lua REPL<br/>[lua-repl.ts]"]
  node_sandbox["REPL sandbox<br/>[sandbox-manager.ts]"]
end

subgraph group_extensions["Advanced features"]
  node_automation["Automation builder<br/>[workflow-engine.ts]"]
  node_sanitizer["Lua sanitization<br/>[lua-sanitizer.ts]"]
  node_webhook["Webhook server<br/>[webhook-server.ts]"]
  node_mqtt["MQTT bridge<br/>[mqtt-bridge.ts]"]
end

node_mcp_client(("MCP client"))
node_home_center["Fibaro Home Center"]

node_mcp_client -->|"starts over stdio"| node_server
node_server -->|"serves tools"| node_handlers
node_handlers -->|"dispatches API calls"| node_fibaro_client
node_fibaro_client -->|"calls REST API"| node_home_center
node_handlers -->|"requests energy data"| node_energy
node_handlers -->|"dispatches bulk tools"| node_bulk
node_bulk -->|"filters devices"| node_bulk_query
node_handlers -->|"dispatches backup tools"| node_backup
node_handlers -->|"dispatches history tools"| node_history
node_handlers -->|"requests analytics"| node_analytics
node_handlers -->|"dispatches template tools"| node_templates
node_templates -->|"loads templates"| node_template_data
node_handlers -->|"dispatches REPL tools"| node_repl
node_repl -->|"manages sessions"| node_sandbox
node_handlers -->|"dispatches automation tools"| node_automation
node_automation -->|"sanitizes Lua"| node_sanitizer
node_automation -->|"deploys scenes"| node_fibaro_client
node_handlers -->|"dispatches integration tools"| node_webhook
node_handlers -->|"dispatches integration tools"| node_mqtt
node_webhook -->|"triggers scene actions"| node_home_center
node_energy -.->|"logs operations"| node_logger

click node_server "https://github.com/ikari-software/fibaro-mcp/blob/main/src/index.ts"
click node_handlers "https://github.com/ikari-software/fibaro-mcp/blob/main/src/mcp-handlers.ts"
click node_fibaro_client "https://github.com/ikari-software/fibaro-mcp/blob/main/src/fibaro-client.ts"
click node_energy "https://github.com/ikari-software/fibaro-mcp/blob/main/src/energy-aggregator.ts"
click node_bulk "https://github.com/ikari-software/fibaro-mcp/blob/main/src/bulk/bulk-operations.ts"
click node_bulk_query "https://github.com/ikari-software/fibaro-mcp/blob/main/src/bulk/query-engine.ts"
click node_backup "https://github.com/ikari-software/fibaro-mcp/blob/main/src/backup/backup-manager.ts"
click node_history "https://github.com/ikari-software/fibaro-mcp/blob/main/src/history/history-manager.ts"
click node_analytics "https://github.com/ikari-software/fibaro-mcp/blob/main/src/history/analytics-engine.ts"
click node_templates "https://github.com/ikari-software/fibaro-mcp/blob/main/src/templates/template-manager.ts"
click node_template_data "https://github.com/ikari-software/fibaro-mcp/tree/main/data/scene-templates"
click node_repl "https://github.com/ikari-software/fibaro-mcp/blob/main/src/repl/lua-repl.ts"
click node_sandbox "https://github.com/ikari-software/fibaro-mcp/blob/main/src/repl/sandbox-manager.ts"
click node_automation "https://github.com/ikari-software/fibaro-mcp/blob/main/src/automation/workflow-engine.ts"
click node_sanitizer "https://github.com/ikari-software/fibaro-mcp/blob/main/src/automation/lua-sanitizer.ts"
click node_webhook "https://github.com/ikari-software/fibaro-mcp/blob/main/src/integrations/webhook-server.ts"
click node_mqtt "https://github.com/ikari-software/fibaro-mcp/blob/main/src/integrations/mqtt-bridge.ts"
click node_logger "https://github.com/ikari-software/fibaro-mcp/blob/main/src/logger.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_handlers,node_mcp_client toneBlue
class node_fibaro_client,node_energy,node_logger toneAmber
class node_bulk,node_bulk_query,node_backup,node_history,node_analytics,node_templates,node_template_data,node_repl,node_sandbox toneMint
class node_automation,node_sanitizer,node_webhook,node_mqtt toneRose
class node_home_center toneIndigo
```

## Components

### MCP interface

- [Server startup](https://github.com/ikari-software/fibaro-mcp/blob/main/src/index.ts): `src/index.ts`
- [Tool handlers](https://github.com/ikari-software/fibaro-mcp/blob/main/src/mcp-handlers.ts): `src/mcp-handlers.ts`

### Fibaro access

- [Fibaro API client](https://github.com/ikari-software/fibaro-mcp/blob/main/src/fibaro-client.ts): `src/fibaro-client.ts`
- [Energy aggregation](https://github.com/ikari-software/fibaro-mcp/blob/main/src/energy-aggregator.ts): `src/energy-aggregator.ts`
- [Logging](https://github.com/ikari-software/fibaro-mcp/blob/main/src/logger.ts): `src/logger.ts`

### Home features

- [Bulk device operations](https://github.com/ikari-software/fibaro-mcp/blob/main/src/bulk/bulk-operations.ts): `src/bulk/bulk-operations.ts`
- [Bulk query engine](https://github.com/ikari-software/fibaro-mcp/blob/main/src/bulk/query-engine.ts): `src/bulk/query-engine.ts`
- [Backup and restore](https://github.com/ikari-software/fibaro-mcp/blob/main/src/backup/backup-manager.ts): `src/backup/backup-manager.ts`
- [History manager](https://github.com/ikari-software/fibaro-mcp/blob/main/src/history/history-manager.ts): `src/history/history-manager.ts`
- [Analytics engine](https://github.com/ikari-software/fibaro-mcp/blob/main/src/history/analytics-engine.ts): `src/history/analytics-engine.ts`
- [Scene templates](https://github.com/ikari-software/fibaro-mcp/blob/main/src/templates/template-manager.ts): `src/templates/template-manager.ts`
- [Template library](https://github.com/ikari-software/fibaro-mcp/tree/main/data/scene-templates): `data/scene-templates`
- [Lua REPL](https://github.com/ikari-software/fibaro-mcp/blob/main/src/repl/lua-repl.ts): `src/repl/lua-repl.ts`
- [REPL sandbox](https://github.com/ikari-software/fibaro-mcp/blob/main/src/repl/sandbox-manager.ts): `src/repl/sandbox-manager.ts`

### Advanced features

- [Automation builder](https://github.com/ikari-software/fibaro-mcp/blob/main/src/automation/workflow-engine.ts): `src/automation/workflow-engine.ts`
- [Lua sanitization](https://github.com/ikari-software/fibaro-mcp/blob/main/src/automation/lua-sanitizer.ts): `src/automation/lua-sanitizer.ts`
- [Webhook server](https://github.com/ikari-software/fibaro-mcp/blob/main/src/integrations/webhook-server.ts): `src/integrations/webhook-server.ts`
- [MQTT bridge](https://github.com/ikari-software/fibaro-mcp/blob/main/src/integrations/mqtt-bridge.ts): `src/integrations/mqtt-bridge.ts`

### Other components

- **MCP client**
- **Fibaro Home Center**

## Connections

- MCP client → Server startup: starts over stdio (evidence: `README.md`)
- Server startup → Tool handlers: serves tools (evidence: `README.md`)
- Tool handlers → Fibaro API client: dispatches API calls (evidence: `src/mcp-handlers.ts`)
- Fibaro API client → Fibaro Home Center: calls REST API (evidence: `src/fibaro-client.ts`)
- Tool handlers → Energy aggregation: requests energy data (evidence: `src/mcp-handlers.ts`)
- Tool handlers → Bulk device operations: dispatches bulk tools (evidence: `src/mcp-handlers.ts`)
- Bulk device operations → Bulk query engine: filters devices (evidence: `src/bulk/bulk-operations.ts`)
- Tool handlers → Backup and restore: dispatches backup tools (evidence: `src/mcp-handlers.ts`)
- Tool handlers → History manager: dispatches history tools (evidence: `src/mcp-handlers.ts`)
- Tool handlers → Analytics engine: requests analytics (evidence: `src/mcp-handlers.ts`)
- Tool handlers → Scene templates: dispatches template tools (evidence: `src/mcp-handlers.ts`)
- Scene templates → Template library: loads templates (evidence: `src/templates/template-manager.ts`)
- Tool handlers → Lua REPL: dispatches REPL tools (evidence: `src/mcp-handlers.ts`)
- Lua REPL → REPL sandbox: manages sessions (evidence: `src/repl/lua-repl.ts`)
- Tool handlers → Automation builder: dispatches automation tools (evidence: `src/mcp-handlers.ts`)
- Automation builder → Lua sanitization: sanitizes Lua (evidence: `src/automation/workflow-engine.ts`)
- Automation builder → Fibaro API client: deploys scenes (evidence: `src/automation/workflow-engine.ts`)
- Tool handlers → Webhook server: dispatches integration tools (evidence: `src/mcp-handlers.ts`)
- Tool handlers → MQTT bridge: dispatches integration tools (evidence: `src/mcp-handlers.ts`)
- Webhook server → Fibaro Home Center: triggers scene actions (evidence: `src/integrations/webhook-server.ts`)
- Energy aggregation → Logging: logs operations
