Unfolded Circle Remote MCP

An independent Model Context Protocol server for reading and configuring an Unfolded Circle Remote Two or Remote 3 through the official Core REST API.

The server exposes activities, touchscreen pages, profiles, integration entities, physical-button mappings, and a generic Core API request tool to MCP clients such as GitHub Copilot CLI.

[!WARNING] This server uses an admin API key and includes write, replacement, delete, and unrestricted request tools. A mistaken tool call can change or remove remote configuration. Back up important setups and test with the core simulator first.

Requirements

• Python 3.10 or newer
• uv for the examples below
• An Unfolded Circle Remote or core simulator reachable from the MCP host
• An admin API key for authenticated endpoints

Run directly from GitHub

UC_REMOTE_URL=http://192.168.1.50 \
UC_API_KEY=replace-me \
uvx --from git+https://github.com/msvinth/uc-remote-mcp uc-remote-mcp

For a local checkout:

uv run uc-remote-mcp

The server uses stdio transport. Configure environment variables in the MCP client rather than expecting the server to read a .env file automatically.

Create an API key

On the remote, generate a web-configurator PIN from the profile/settings view. Then run the helper from a clone:

./scripts/setup-api-key.sh 192.168.1.50

The PIN is read from a hidden prompt instead of a command-line argument. The new key is printed once; store it securely.

MCP client configuration

Add this entry under mcpServers:

{
  "mcpServers": {
    "unfolded-circle": {
      "type": "local",
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "git+https://github.com/msvinth/uc-remote-mcp",
        "uc-remote-mcp"
      ],
      "env": {
        "UC_REMOTE_URL": "http://192.168.1.50",
        "UC_API_KEY": "replace-me"
      },
      "tools": ["*"]
    }
  }
}

Keep the configuration file private because it contains the API key.

Home Assistant Copilot Terminal

The Copilot Terminal app in /Users/msvinth/private/home-assistant-apps/copilot-terminal already includes uvx, uses Python 3.12 for MCP servers, starts in /config, and persists Copilot data at /data/home/.copilot/.

Its MCP config is:

/data/home/.copilot/mcp-config.json

Retain the existing home-assistant entry and add unfolded-circle beside it:

{
  "mcpServers": {
    "home-assistant": {
      "type": "local",
      "command": "uvx",
      "args": [
        "--index-strategy",
        "unsafe-best-match",
        "--python",
        "3.12",
        "ha-mcp"
      ],
      "env": {
        "HOMEASSISTANT_URL": "http://supervisor/core",
        "HOMEASSISTANT_TOKEN": "provided-by-the-app"
      },
      "tools": ["*"]
    },
    "unfolded-circle": {
      "type": "local",
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "git+https://github.com/msvinth/uc-remote-mcp",
        "uc-remote-mcp"
      ],
      "env": {
        "UC_REMOTE_URL": "http://192.168.1.50",
        "UC_API_KEY": "replace-me"
      },
      "tools": ["*"]
    }
  }
}

The current Copilot Terminal setup-ha-mcp.sh regenerates this file at app startup with only the Home Assistant entry. A manual merge can therefore be overwritten on restart. Persistent automatic registration should be added later as an optional feature in that sibling project; this repository does not modify the app.

Configuration

Variable	Required	Description
UC_REMOTE_URL	Yes	Remote origin only, such as http://192.168.1.50; do not include /api.
UC_API_KEY	For authenticated tools	Admin API key created by the remote.
UC_TIMEOUT	No	Positive request timeout in seconds; defaults to 20.

Tools

Discovery and escape hatch: uc_ping, uc_ui_reference, uc_request, get_screen_layout.

Entities: list_entities, get_entity.

Integrations: list_integration_instances, list_available_entities, configure_entities.

Activities: list_activities, get_activity, get_activity_ui_pages, get_activity_ui_page, create_activity_ui_page, update_activity_ui_page, delete_activity_ui_page, reorder_activity_ui_pages, get_activity_buttons.

Profiles and groups: list_profiles, get_profile, get_profile_pages, get_profile_page, update_profile_page, get_profile_groups, list_activity_groups.

There are 25 tools in total. uc_request can call any Core REST API endpoint available to the configured key.

Suggested workflow

1. Call uc_ping.
2. Inspect the target activity, profile, or page.
3. Call uc_ui_reference before constructing UI payloads.
4. Make the smallest possible update.
5. Read the object again to confirm the result.

An entity provided by Home Assistant or another integration must be configured on the remote before it can be placed on a page. Use list_integration_instances, list_available_entities, and configure_entities in that order.

Compatibility

The package targets the current MCP Python SDK v2 and Python 3.10+. Its endpoint coverage was reviewed against Unfolded Circle REST Core API 0.46.x. The Core API is pre-1.0 and may change between firmware releases.

Home Assistant entity support depends on the remote's integration driver: integration-home-assistant.

Development

uv sync
uv run ruff check .
uv run ruff format --check .
uv run pytest
uv build

See SECURITY.md before reporting credential or command-execution issues.

License and attribution

Original code and documentation in this repository are licensed under the MIT License.

Unfolded Circle API specifications and documentation have their own upstream licenses. This project links to those sources and does not relicense them. Unfolded Circle is a trademark of its respective owner. This community project is not affiliated with or endorsed by Unfolded Circle.