# README

![OrbitEOS](https://img.shields.io/badge/OrbitEOS-Energy_Management_for_the_AI_Era-000?style=for-the-badge\&labelColor=0f172a\&color=134e4a)\ <sub>Real-time energy monitoring & AI-powered control for solar, battery, and grid.</sub>\
\
[![Website](https://img.shields.io/badge/Website-orbiteos.com-2dd4bf?style=flat-square\&logo=googlechrome\&logoColor=white)](https://orbiteos.com)  [![App](https://img.shields.io/badge/App-app.orbiteos.cloud-8b5cf6?style=flat-square\&logo=rocket\&logoColor=white)](https://app.orbiteos.cloud)  [![MCP](https://img.shields.io/badge/MCP_Server-Live-10b981?style=flat-square\&logo=bolt\&logoColor=white)](https://mcp.orbiteos.cloud/mcp)  [![Docs](https://img.shields.io/badge/Docs-API-3b82f6?style=flat-square\&logo=readthedocs\&logoColor=white)](https://mcp.orbiteos.cloud/docs)

### What is OrbitEOS?

OrbitEOS is an intelligent energy management platform that combines **real-time monitoring**, **AI-powered control**, and **multi-site management** into one extensible system. It works natively with AI assistants like Claude and ChatGPT through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io).

<br>

### Platform Overview

| <p><br><img src="https://readme-typing-svg.demolab.com/?font=JetBrains+Mono&#x26;weight=500&#x26;size=15&#x26;duration=800&#x26;pause=5000&#x26;color=2DD4BF&#x26;center=true&#x26;vCenter=true&#x26;multiline=true&#x26;repeat=true&#x26;width=480&#x26;height=200&#x26;lines=%E2%98%80+Solar+7.2+kW+%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%AC%E2%94%80%E2%94%80%E2%94%80%E2%94%80+%F0%9F%8F%A0+Home;%F0%9F%94%8B+Battery+85%25+%E2%94%80%E2%94%80%E2%94%A4+OrbitEOS+%E2%94%9C%E2%94%80+4.1+kW;%E2%9A%A1+Grid+%E2%86%900.8+kW+%E2%94%80%E2%94%98+Router++%E2%94%82;%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80%E2%94%80;AI+optimizes+every+watt+%E2%9A%A1" alt="Energy Flow"><br></p> |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |

| <p><br><img src="https://img.shields.io/badge/-%E2%98%80%EF%B8%8F-000?style=flat-square&#x26;labelColor=000&#x26;color=000" alt=""><br><br><strong>Live Energy Dashboard</strong><br><br><sub>Real-time power flow visualization showing every watt moving through your system: solar, battery, grid, and consumption.</sub><br><br></p> | <p><br><img src="https://img.shields.io/badge/-%F0%9F%A4%96-000?style=flat-square&#x26;labelColor=000&#x26;color=000" alt=""><br><br><strong>AI-Powered Control</strong><br><br><sub>Ask questions and give commands in natural language through Claude, ChatGPT, or any MCP-compatible AI assistant.</sub><br><br></p> |  <p><br><img src="https://img.shields.io/badge/-%F0%9F%94%8B-000?style=flat-square&#x26;labelColor=000&#x26;color=000" alt=""><br><br><strong>Battery Intelligence</strong><br><br><sub>Smart charge and discharge optimization that learns your patterns and maximizes self-consumption.</sub><br><br></p>  |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|              <p><br><img src="https://img.shields.io/badge/-%E2%9A%A1-000?style=flat-square&#x26;labelColor=000&#x26;color=000" alt=""><br><br><strong>Grid Optimization</strong><br><br><sub>Peak shaving, self-consumption maximization, and demand response to automatically reduce electricity costs.</sub><br><br></p>              |  <p><br><img src="https://img.shields.io/badge/-%F0%9F%8F%A2-000?style=flat-square&#x26;labelColor=000&#x26;color=000" alt=""><br><br><strong>Multi-Site Management</strong><br><br><sub>Hierarchical site tree with role-based access control. Manage regions, hubs, sites, and zones from one pane.</sub><br><br></p> | <p><br><img src="https://img.shields.io/badge/-%F0%9F%A7%A9-000?style=flat-square&#x26;labelColor=000&#x26;color=000" alt=""><br><br><strong>Marketplace</strong><br><br><sub>Extend with plugins for device drivers, analytics, control strategies, notifications, and dashboard widgets.</sub><br><br></p> |

<br>

### How It Works

| <p><br><img src="https://img.shields.io/badge/1-Connect-2dd4bf?style=for-the-badge&#x26;labelColor=0f172a" alt="Step 1"><br><br>Link your energy system — inverters, meters, batteries, EV chargers. Supports all major brands through the marketplace.<br><br></p> | <p><br><img src="https://img.shields.io/badge/2-Monitor-8b5cf6?style=for-the-badge&#x26;labelColor=0f172a" alt="Step 2"><br><br>See real-time energy flows, historical analytics, and system health. Track performance across all your sites.<br><br></p> | <p><br><img src="https://img.shields.io/badge/3-Optimize-f59e0b?style=for-the-badge&#x26;labelColor=0f172a" alt="Step 3"><br><br>AI assistants analyze your patterns, suggest optimizations, and control your system through natural conversation.<br><br></p> |
| :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |

<br>

### MCP Integration

OrbitEOS exposes a full [Model Context Protocol](https://modelcontextprotocol.io) server, giving AI assistants direct access to your energy system. No custom code needed — just connect and talk.

#### Quick Setup

**Claude Code / Claude Desktop:**

```bash
claude mcp add orbiteos https://mcp.orbiteos.cloud/mcp
```

**Any MCP client:** Point to `https://mcp.orbiteos.cloud/mcp` (Streamable HTTP transport).

**OpenAI ChatGPT:** Available as a ChatGPT action — search "OrbitEOS" in the GPT store.

#### AI Conversation Example

| <p>   <strong>You:</strong> <em>"Is my system running normally?"</em></p><p>   <strong>OrbitEOS:</strong></p><blockquote><p><strong>System Online</strong></p><p>Self-sufficiency today: <strong>94%</strong> — No warnings or errors detected.</p></blockquote> |                            |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| Component                                                                                                                                                                                                                                                        | Status                     |
| Solar                                                                                                                                                                                                                                                            | 7.2 kW (producing)         |
| Battery                                                                                                                                                                                                                                                          | 85% SoC (charging +2.3 kW) |
| Grid                                                                                                                                                                                                                                                             | Exporting 0.8 kW           |
| Consumption                                                                                                                                                                                                                                                      | 4.1 kW                     |
| Components                                                                                                                                                                                                                                                       | All 12 healthy             |

#### What You Can Do

| Category             | Example                                                                                 |
| -------------------- | --------------------------------------------------------------------------------------- |
| **System Health**    | *"Is my system running normally?"* — checks online status, battery SoC, grid connection |
| **Live Monitoring**  | *"What's my current solar production?"* — real-time power values                        |
| **Energy Analytics** | *"How much solar did I generate this month?"* — historical energy totals                |
| **Grid Analysis**    | *"Why am I importing so much from the grid?"* — production vs consumption patterns      |
| **Solar Comparison** | *"Compare my solar this week vs last week"* — period-over-period analysis               |
| **Battery Insights** | *"Should I get a bigger battery?"* — charge/discharge analysis, sizing recommendations  |
| **Control**          | *"Set battery to charge from grid overnight"* — write to controllable channels          |
| **Configuration**    | *"Add a new site called Munich Factory"* — create sites, users, roles                   |
| **Marketplace**      | *"What plugins are available for SMA inverters?"* — browse, install, assign             |
| **Diagnostics**      | *"Show me error logs from today"* — system logs by level and date                       |

#### 50+ MCP Tools

<details>

<summary>View all tools by domain</summary>

<br>

| Domain            | Tools                                                                                                                                                                                                                         |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Live Data**     | `get_live_data` `get_channel_value` `set_channel_value`                                                                                                                                                                       |
| **History**       | `query_history` `query_energy_totals` `export_csv`                                                                                                                                                                            |
| **Diagnostics**   | `check_system_health` `analyze_grid_usage` `compare_solar_performance` `analyze_battery_usage` `get_energy_summary`                                                                                                           |
| **Sites**         | `list_sites` `search_sites` `create_site` `update_site` `delete_site` `get_site` `get_site_config` `describe_site`                                                                                                            |
| **Users & Roles** | `list_users` `get_user` `create_user` `update_user` `delete_user` `invite_user` `list_roles` `create_role` `update_role` `delete_role` `list_permissions`                                                                     |
| **Accounts**      | `list_accounts` `create_account` `update_account` `list_sub_accounts` `create_sub_account` `update_sub_account` `delete_sub_account`                                                                                          |
| **Marketplace**   | `list_marketplace_categories` `browse_plugins` `get_plugin_details` `install_plugin` `list_installed_plugins` `update_plugin_config` `uninstall_plugin` `assign_plugin_to_site` `remove_plugin_from_site` `list_site_plugins` |
| **Components**    | `create_component` `update_component` `delete_component`                                                                                                                                                                      |
| **System**        | `get_system_log` `execute_command` `get_audit_log` `check_platform_health` `describe_system`                                                                                                                                  |
| **Platform**      | `get_platform_settings` `update_platform_settings` `test_smtp` `universal_search`                                                                                                                                             |

</details>

<br>

### Architecture

|                                      Clients                                      |                                                                       |                                                                                     |                                                                                |
| :-------------------------------------------------------------------------------: | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| <p><strong>Web App</strong><br><sub>Dashboard, analytics, configuration</sub></p> | <p><strong>Mobile App</strong><br><sub>Monitoring on the go</sub></p> | <p><strong>AI Assistants</strong><br><sub>Claude, ChatGPT, any MCP client</sub></p> | <p><strong>Custom Integrations</strong><br><sub>REST API & WebSocket</sub></p> |

↓

|                                                                                       Platform                                                                                       |                                                                                                    |                                                                                            |
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|                                          <p><strong>REST API</strong><br><sub>Full CRUD for sites, users, roles, accounts, plugins</sub></p>                                         | <p><strong>WebSocket</strong><br><sub>Real-time live data streaming & push notifications</sub></p> | <p><strong>MCP Server</strong><br><sub>50+ tools for AI-native energy management</sub></p> |
| <p><strong>Core Engine</strong><br><sub>Authentication  •  Role-Based Access Control  •  Multi-Tenant Accounts  •  Site Hierarchy  •  Plugin Marketplace  •  Audit Logging</sub></p> |                                                                                                    |                                                                                            |

↓

|                                                                          Edge                                                                          |                                                                            |                                                                             |                                                                           |
| :----------------------------------------------------------------------------------------------------------------------------------------------------: | -------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|                                    <p><strong>Inverters</strong><br><sub>SMA, Fronius, Huawei, GoodWe, ...</sub></p>                                   | <p><strong>Meters</strong><br><sub>Grid, production, consumption</sub></p> | <p><strong>Batteries</strong><br><sub>BYD, Tesla, LG, Sonnen, ...</sub></p> | <p><strong>EV Chargers</strong><br><sub>KEBA, Wallbox, ABL, ...</sub></p> |
| <p><strong>Edge Controller</strong><br><sub>On-site optimization  •  Peak shaving  •  Self-consumption  •  Smart charging  •  Grid balancing</sub></p> |                                                                            |                                                                             |                                                                           |

<br>

### Use Cases

| <p><br></p><p><strong>Residential</strong></p><p>Maximize solar self-consumption with smart battery management. OrbitEOS learns your household patterns and optimizes when to store, use, or export energy — reducing your electricity bill automatically.</p><blockquote><p><em>"How can I reduce my grid import?"</em></p></blockquote><p><br></p> | <p><br></p><p><strong>Commercial & Industrial</strong></p><p>Reduce peak demand charges with load management, peak shaving, and grid optimization. Monitor multiple sites from a single dashboard.</p><blockquote><p><em>"What were my peak demand charges this month vs last month?"</em></p></blockquote><p><br></p>          |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p><br></p><p><strong>Energy Communities</strong></p><p>Manage distributed assets at scale with hierarchical site management (regions → hubs → sites → zones). Aggregate analytics across hundreds of installations.</p><blockquote><p><em>"Summary of all sites with below-average solar performance this week."</em></p></blockquote><p><br></p>   | <p><br></p><p><strong>Solar Installers & O\&M</strong></p><p>Monitor your fleet of customer installations. Get proactive alerts when systems underperform. Use AI for rapid diagnostics across your portfolio.</p><blockquote><p><em>"Check system health for all sites in the Munich region."</em></p></blockquote><p><br></p> |

<br>

### Tech Stack

<div align="center"><img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&#x26;logo=typescript&#x26;logoColor=white" alt=""> <img src="https://img.shields.io/badge/React_18-61DAFB?style=flat-square&#x26;logo=react&#x26;logoColor=black" alt=""> <img src="https://img.shields.io/badge/Node.js-339933?style=flat-square&#x26;logo=node.js&#x26;logoColor=white" alt=""> <img src="https://img.shields.io/badge/PostgreSQL-4169E1?style=flat-square&#x26;logo=postgresql&#x26;logoColor=white" alt=""> <img src="https://img.shields.io/badge/Docker-2496ED?style=flat-square&#x26;logo=docker&#x26;logoColor=white" alt=""> <img src="https://img.shields.io/badge/WebSocket-Real--time-f59e0b?style=flat-square" alt=""> <img src="https://img.shields.io/badge/MCP-Model_Context_Protocol-8b5cf6?style=flat-square" alt=""></div>

<br>

### Links

|                                                                      |                     |
| :------------------------------------------------------------------: | :-----------------: |
|               [**orbiteos.com**](https://orbiteos.com)               |       Website       |
|         [**app.orbiteos.cloud**](https://app.orbiteos.cloud)         |      Launch App     |
|    [**mcp.orbiteos.cloud/docs**](https://mcp.orbiteos.cloud/docs)    |  API Documentation  |
|     [**mcp.orbiteos.cloud/mcp**](https://mcp.orbiteos.cloud/mcp)     | MCP Server Endpoint |
| [**mcp.orbiteos.cloud/privacy**](https://mcp.orbiteos.cloud/privacy) |    Privacy Policy   |

<br>

**<hello@orbiteos.cloud>**

<sub>Built by OrbitEOS</sub>