MCP

What is the nomos MCP Skill?

The nomos MCP Skill allows AI assistants like Claude to communicate directly with the nomos system Controller. Using the standardized Model Context Protocol (MCP), the AI can control devices, execute scenes, manage rooms, create automations, and much more – all through natural language.

Prerequisites

An MCP-compatible client (e.g. Claude Desktop, Claude Code, Cursor, Windsurf)
Node.js (version 18 or higher) installed on your machine
Network access to the nomos system Controller (local only, no external access possible)

Setup

Step 1: Enable the MCP Module in nomos

The MCP module must be enabled in the nomos configuration interface. Navigate to Skills and make sure the MCP module is turned on.

Step 2: Create a Token

In the nomos configuration interface, navigate to the MCP section and create a new token. This token is used to authenticate the AI client with the nomos system Controller. Take note of the token – you will need it for the client configuration.

Each token can be given a custom name (e.g. "Claude Desktop Office")
Tokens can be disabled or deleted at any time
Multiple tokens can be created for different clients

Step 3: Configure the Client

There are two ways to connect your MCP client to the nomos system Controller:

Option A: nomos MCP Bridge (recommended) – a dedicated proxy that manages controller connections via a setup page. Simplest setup, supports multiple controllers, works with all MCP clients.
Option B: Direct Connection – configure the controller URL and token directly in the client configuration. Requires manual token handling.

Option A: nomos MCP Bridge (Recommended)

The nomos MCP Bridge is a lightweight local proxy that manages connections to one or more nomos system controllers. Instead of configuring URLs and tokens directly, you register controllers via a web-based setup page. The bridge works with any MCP client that supports stdio-based servers.

Claude Desktop

Open the Claude Desktop settings and navigate to the "MCP Servers" section. Add a new server with the following configuration:

json

{
  "mcpServers": {
    "nomos": {
      "command": "npx",
      "args": ["-y", "nomos-mcp-bridge"]
    }
  }
}

Claude Code (CLI)

bash

claude mcp add nomos -- npx -y nomos-mcp-bridge

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

json

{
  "mcpServers": {
    "nomos": {
      "command": "npx",
      "args": ["-y", "nomos-mcp-bridge"]
    }
  }
}

Windsurf

Add to your Windsurf MCP config (~/.codeium/windsurf/mcp_config.json):

json

{
  "mcpServers": {
    "nomos": {
      "command": "npx",
      "args": ["-y", "nomos-mcp-bridge"]
    }
  }
}

Other MCP-Compatible Clients

Any client supporting stdio-based MCP servers can use the bridge. The command is:

npx -y nomos-mcp-bridge

Managing Controllers

After configuring the bridge in your MCP client, you can manage your controllers using the following AI commands:

Command	Description
`open_setup`	Opens the web-based setup page in your browser where you can enter the controller name, URL and MCP token
`add_controller`	Adds a new controller directly via AI — provide the name, URL and token
`list_controllers`	Lists all registered controllers and shows which one is currently selected
`select_controller`	Connects to a registered controller by name
`remove_controller`	Removes a registered controller

Option B: Direct Connection

If you prefer to configure the controller URL and token directly without using the bridge, you can use the following configurations.

Claude Desktop

Claude Desktop does not natively support the Streamable HTTP transport protocol. The connection is established via the mcp-remote package, which acts as a bridge.

Open the Claude Desktop settings and navigate to the "MCP Servers" section. Add a new server with the following configuration:

json

{
  "mcpServers": {
    "nomos": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://<nomos-ip>/mcp",
        "--allow-http",
        "--header",
        "Authorization: Bearer <your-token>"
      ]
    }
  }
}

Replace <nomos-ip> with the IP address or hostname of your nomos system Controller and <your-token> with the token created in Step 2.

INFO

Note: The --allow-http parameter is required because the nomos system Controller is accessible locally via HTTP (not HTTPS).

Claude Code (CLI)

Claude Code natively supports Streamable HTTP. Add the server via the command line:

bash

claude mcp add nomos \
  --transport streamable-http \
  "http://<nomos-ip>/mcp" \
  --header "Authorization: Bearer <your-token>"

Or configure it manually in ~/.claude/settings.json:

json

{
  "mcpServers": {
    "nomos": {
      "type": "streamable-http",
      "url": "http://<nomos-ip>/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Cursor

Cursor natively supports Streamable HTTP. Navigate to Settings > MCP and add a new server:

json

{
  "mcpServers": {
    "nomos": {
      "type": "streamable-http",
      "url": "http://<nomos-ip>/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

If the connection cannot be established, you can alternatively use the mcp-remote variant as described for Claude Desktop.

Windsurf

Windsurf natively supports Streamable HTTP. Open the MCP configuration and add:

json

{
  "mcpServers": {
    "nomos": {
      "type": "streamable-http",
      "url": "http://<nomos-ip>/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Other MCP-Compatible Clients

The nomos MCP server uses the Streamable HTTP transport protocol. Clients that natively support this standard can be configured directly:

URL: http://<nomos-ip>/mcp
Authentication: Bearer token in the Authorization header
Transport type: Streamable HTTP

For clients that only support stdio-based MCP servers (like Claude Desktop), mcp-remote can be used as a bridge:

bash

npx mcp-remote http://<nomos-ip>/mcp --allow-http --header "Authorization: Bearer <your-token>"

Feature Overview

Resources

The AI has access to real-time data from your nomos system Controller:

All components, scenes, rooms, floors, timers, and automations as overview lists
Individual entities with detailed information (e.g. a specific device with all its properties)
Live updates: Changes in the system are automatically reported to the AI

Built-in Prompts

Status & Overview

Prompt	Description
`home_status`	Comprehensive overview of the current state of the entire system — all rooms, components, and their values
`room_status`	Current status of all components in a specific room (room name or room ID as parameter)
`system_health`	Comprehensive health check of the system — connectivity, unreachable devices, cloud status, remote access, critical notifications

Domain-Specific Reports

Prompt	Description
`climate_report`	Summary of temperature, humidity, and climate control across all rooms
`energy_report`	Summary of energy consumption and power-related data from all components
`security_status`	Summary of all security-related sensors — door/window contacts, motion detectors, locks, alarms
`notifications_summary`	Summary of all current notifications, grouped by severity and type
`automation_overview`	Overview of all automations and timers — their status, triggers, and actions

Guided Creation Workflows

Prompt	Description
`create_scene`	Guided workflow to create a new scene based on a description of the desired state
`create_automation`	Guided workflow to create a new automation based on a description of the desired behavior
`create_timer`	Guided workflow to create a new timer-based automation

Examples

Controlling Devices

"Turn on the light in the living room."

"Dim the ceiling lamp in the bedroom to 50%."

"Set the heating in the bathroom to 22 degrees."

Querying Status

"Which windows are currently open?"

"Show me the status of all devices in the living room."

"What is the current temperature in the kitchen?"

Managing Scenes

"Create a scene called 'Movie Night' that dims the living room lights and closes the blinds."

"Execute the 'Good Morning' scene."

Creating Automations

"Create an automation that turns on the outdoor lights at sunset."

"Show me all active timers."

KNX Configuration

"Which KNX group addresses are available in the project?"

"Import the KNX project from the file."

Important Notes and Known Limitations

Local Access Only

The MCP endpoint is only accessible via the local network. Access from outside (e.g. via the internet) is blocked by the system. The MCP client must be on the same network as the nomos system Controller.

Claude Desktop: Restart on Connection Loss

WARNING

Important: If the connection between Claude Desktop and the nomos MCP server is interrupted (e.g. due to a nomos system Controller restart or network issues), Claude Desktop must be fully restarted. Simply closing and reopening the chat window is not sufficient – the application must be completely quit and restarted in order to re-establish the MCP connection.

Token Security

Treat MCP tokens like passwords
Create separate tokens for different clients
Disable or delete tokens that are no longer needed
Tokens grant full access to all MCP functions – there is no fine-grained permission management

General MCP Notes

Session management: Each client receives its own session. Multiple clients can be connected simultaneously.
Automatic notifications: Changes in the system (e.g. device status) are automatically reported to all connected clients. There may be a short delay with many simultaneous changes (debouncing of 100ms).
Error handling: If a tool returns an error, the AI will typically recognize this and display a helpful error message.

Usage Tips

Be as specific as possible in your instructions (room names, device names)
The AI can combine multiple actions in a single request
Use the built-in prompts for common tasks
For complex automations, it is recommended to build them step by step with the AI

Addons

AppleTV

Eltako

KNX

Wiser by Feller

ZigBee

Users

Advanced

MCP

What is the nomos MCP Skill?

Prerequisites

Setup

Step 1: Enable the MCP Module in nomos

Step 2: Create a Token

Step 3: Configure the Client

Option A: nomos MCP Bridge (Recommended)

Option B: Direct Connection

Feature Overview

Resources

Built-in Prompts

Examples

Controlling Devices

Querying Status

Managing Scenes

Creating Automations

KNX Configuration

Important Notes and Known Limitations

Local Access Only

Claude Desktop: Restart on Connection Loss

Token Security

General MCP Notes

Usage Tips

MCP ​

What is the nomos MCP Skill? ​

Prerequisites ​

Setup ​

Step 1: Enable the MCP Module in nomos ​

Step 2: Create a Token ​

Step 3: Configure the Client ​

Option A: nomos MCP Bridge (Recommended) ​

Option B: Direct Connection ​

Feature Overview ​

Resources ​

Built-in Prompts ​

Examples ​

Controlling Devices ​

Querying Status ​

Managing Scenes ​

Creating Automations ​

KNX Configuration ​

Important Notes and Known Limitations ​

Local Access Only ​

Claude Desktop: Restart on Connection Loss ​

Token Security ​

General MCP Notes ​

Usage Tips ​

MCP

What is the nomos MCP Skill?

Prerequisites

Setup

Step 1: Enable the MCP Module in nomos

Step 2: Create a Token

Step 3: Configure the Client

Option A: nomos MCP Bridge (Recommended)

Option B: Direct Connection

Feature Overview

Resources

Built-in Prompts

Examples

Controlling Devices

Querying Status

Managing Scenes

Creating Automations

KNX Configuration

Important Notes and Known Limitations

Local Access Only

Claude Desktop: Restart on Connection Loss

Token Security

General MCP Notes

Usage Tips