@openremote/mcp-server

⚠️ Beta — early work. API may change before 1.0. Use in production at your own risk. Feedback welcome via GitHub Issues.

A Model Context Protocol server for the OpenRemote IoT platform. Exposes asset and attribute operations as tools and resources for AI assistants like Claude Desktop and Claude Code.

Capabilities

Tools (10)

Tool	Purpose
query_assets	Search assets by type, realm, parent, name, ids
get_asset	Read a single asset incl. attributes
create_asset	Create a new asset
update_asset	Partial update; merges attributes by default
delete_assets	Bulk delete by ids
get_attribute	Read one attribute (value + meta)
write_attribute	Write a single attribute value
write_attributes	Bulk write across assets
get_attribute_history	Time-series datapoints (lttb/all/interval/nearest)
update_attribute_meta	Partial-merge meta on one attribute (label, units, ruleState, …)
get_asset_types	List asset type descriptors
get_value_descriptors	List value type descriptors
get_meta_item_descriptors	List meta item descriptors

Resources (4)

URI	What
openremote://asset-model/types	Catalog of asset types and their attribute descriptors
openremote://asset-model/values	Catalog of value types and constraints
openremote://asset-model/meta	Catalog of meta item descriptors
openremote://realm/{name}	A realm definition (templated; list enumerates accessible realms)

Install

Run on demand with npx:

npx -y @openremote/mcp-server

Or install globally:

npm install -g @openremote/mcp-server
openremote-mcp

Configuration

All configuration is via environment variables.

Variable	Required	Default	Description
OPENREMOTE_HOST	yes	—	Full URL, e.g. https://demo.openremote.io
OPENREMOTE_CLIENT_ID	yes	—	Service user client id
OPENREMOTE_CLIENT_SECRET	yes	—	Service user client secret
OPENREMOTE_REALM	no	master	Realm of the service user

Service user setup

1. Log into OpenRemote as a realm admin.
2. Create a service user in the relevant realm (master recommended for cross-realm access).
3. Grant roles: at minimum read:assets, write:assets. Add read:admin/write:admin for realm visibility.
4. Copy the generated client id and secret into the env vars above.

Quickstart — Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform:

{
  "mcpServers": {
    "openremote": {
      "command": "npx",
      "args": ["-y", "@openremote/mcp-server"],
      "env": {
        "OPENREMOTE_HOST": "https://your-instance.openremote.io",
        "OPENREMOTE_CLIENT_ID": "your-service-user",
        "OPENREMOTE_CLIENT_SECRET": "your-secret"
      }
    }
  }
}

Restart Claude Desktop. Try: "list assets in master realm" or "attach the asset-types catalog as context".

Quickstart — Claude Code

claude mcp add openremote -- npx -y @openremote/mcp-server

Set env vars in your shell profile or per-project .env.

Local development

git clone https://github.com/openremote/mcp-server.git
cd mcp-server
npm install
cp .env.example .env   # then fill in values
npm run typecheck
npm test
npm run build
node dist/index.js     # starts on stdio

Use the official MCP Inspector to test interactively:

npx @modelcontextprotocol/inspector node dist/index.js

License

AGPL-3.0-or-later. Copyright OpenRemote contributors.