# Unfolded Circle Remote MCP

An independent Model Context Protocol server for reading and configuring an
[Unfolded Circle](https://www.unfoldedcircle.com/) Remote Two or Remote 3
through the official [Core REST API](https://unfoldedcircle.github.io/core-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](https://github.com/unfoldedcircle/core-simulator) first.

## Requirements

- Python 3.10 or newer
- [`uv`](https://docs.astral.sh/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

```bash
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:

```bash
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:

```bash
./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`:

```json
{
  "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:

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

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

```json
{
  "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](https://github.com/unfoldedcircle/integration-home-assistant).

## Development

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

See [SECURITY.md](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](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.